python - How to make pages in MkDocs's side menu expandable?

Question

I tried searching for this, but was unable to get any sort of answer that would be pointing to a solution. Let me start with some background first i suppose.

My Goal:

I'm currently figuring out how to get a decent automated documentation created for a certain python script repository. Its a library, so not a 'project' per se. It also lives in it's own place, as it's not maintained by a standalone python installation, but a Python 2.7 implementation that comes with Autodesk Maya. As such, there's a bunch of modules in the library, organized the way it makes sense for us, and all functions have a docstring that is written according to the reStructuredText (:param parameterName: Description, etc..). I was looking for something that would scrub through the whole repository, and create a nice html documentation that would look neat and make it easy to search for existing functions, thinking it must exist, but alas, i was unable to find anything that would be that user friendly.

What i tried:

Sphinx, pdoc3 - both proven various levels of not-idealness.

What i decide to do:

The last i tried is mkdocs. It seems fairly simplistic, not only because it doesnt actually do anything but create a stub of a page that gets filled based on one .yaml config file and per-page .md files that the user has to supply. Now FYI, im new to both yaml and md, as i never had to use either. I have decided to create myself a wrapper (for one-button-to-make-docs function) that would basically run through my python library, creating a .md page per module, and filling it with the functions/classes and their docstrings. I would have to parse the docstrings myself, but that's not that big a deal. This would basically turn mkdocs into a pretty decent automated documentation with no needed manual input. Now... I do like the theme readthedocs that you can set for your documentation in the yaml config file, but this is where i get stuck.

My Issue

When i 'mkdocs serve' my site, i'd like anything that has a hierarchy in the side menu, to be collapsible, like in this example (note the collapse/expand icons on the left sidebar):

But what I'm getting is no collapsability:

It should be noted, i suppose, that in my case, the 'attr' section is one .md site, that has just a simple structure of a h3 header per function name, and some description under, before having a horizontal rule to divide from the next function.

Also, in the yaml config file for the mydocs structure, the structure is kept very simple:

site_name: My Repo
nav:
    - Home: 'index.md'
    - 'Modules':
        - attr: 'pageA.md'
        - pageB: 'pageB.md'
        - pageC: 'pageC.md'
    - About: 'about.md'
theme:
    name: readthedocs
    include_homepage_in_sidebar: false
    highlightjs: true
    hijs_languages:
        - python
markdown_extensions:
    - toc:
        permalink: True
        separator: "_"

So the question is - how would i go about making my sidebar have little expand/collapse icons? (namely the attr site at this point) Is it doable? Is it doable through the yaml config file, or the .md files of each page?

And potentially, is there a better alternative to what im doing, that wouldn't require me to write my own docs-making one-button solution?

Thank you!

question from:https://stackoverflow.com/questions/65867653/how-to-make-pages-in-mkdocss-side-menu-expandable

Answer 1

Perhaps, you just need to write it differently. This is how it works in my project:

nav:
  - 'index.md'
  - 'glossary.md'
  - 'Subject1':
    - 'dir/file1.md'
    - 'dir/file2.md'
  - 'Subject2':
    - 'NestedSubject2_1':
      - 'dir/file1.md'
      - 'dir/file2.md'
    - 'NestedSubject2_2':
      - 'dir/file.md'
      - 'dir/file2.md'
      - 'dir/file3.md'
      - 'dir/file4.md'

And this is the least I can show, sorry. That's the structure my project has.