Collapse navigation sidebar

[po09i]

The sidebar using RTD's theme is currently uncollapsed everywhere. We want it to be collapsed when entering the website

[po09i]

MkDocs RTD theme copies the original RTD theme. The original theme only supports 2 levels of nesting as documented in this issue:

• index
• overview_folder
  • introduction
  • flowchart
• etc

Introduction being a single markdown file. To have more levels in the TOC, RTD uses the different heading levels in a markdown file :

In this screenshot, the assembly and amplifier files were moved to only have one level of nesting. This fixes this issue but requires changing our website layout to only have 1 level of nesting, change helpDocMd to generate a single file with different header levels (potential problems with header levels (max 4 as seen in the screenshot)). As mentioned above, this is the desired way to use RTD's theme so no fix is in the pipeline for that.

I imagine bringing all nested folders to the 2nd level :

• index
• overview_folder
  • introduction
  • flowchart
• ...
• Contributing
  • API documentation
• Other ressources
  • Hardware assembly
  • Hardware description

The problem is with the API doc which requires multiple header levels. The maximum depth displayed in the TOC is 4, therefore the furthest a function can be documented is the 4th level, the maximum depth of a class is the 3rd level so that methods can be displayed in the TOC. This does not leave much room for packages. I see this solution a potential limitation for now and the future. Here is an example :

# API documentation (Header 1)
## Coils (Header 2)
### Siemens (Header 3)
#### Function (Header 4)
##### Attributes (Header 5)

Another approach is reverting to MkDocs default theme which supports our current documentation format. @jcohenadad

[jcohenadad]

@po09i i'm not sure i fully understand the cause of the problem. In this comment, it looks like the RTD MkDocs theme did well with 2+ nesting, no?

Or is the problem caused by files nested (i.e. having multiple depth of folders)?

[po09i]

@jcohenadad

Or is the problem caused by files nested (i.e. having multiple depth of folders)?

Yes the problem is having multiple files nested, sorry for not being clear... The comment you mentioned uses the headers of a markdown file to have more in the TOC (which is also what was done in the image I linked above).

[jcohenadad]

ha! maybe this would fix the problem? https://github.com/cjsheets/mkdocs-rtd-dropdown#how-to-use

[po09i]

ha! maybe this would fix the problem? https://github.com/cjsheets/mkdocs-rtd-dropdown#how-to-use

This used to fix an issue that has now been fixed within the built in MkDocs RTD theme. The behaviour is the same as mentioned above in this comment. The expected way to use the theme is to have 1 level of file nesting and markdown files with headers.

[jcohenadad]

ha! maybe this would fix the problem? https://github.com/cjsheets/mkdocs-rtd-dropdown#how-to-use

This used to fix an issue that has now been fixed within the built in MkDocs RTD theme. The behaviour is the same as mentioned above in this comment. The expected way to use the theme is to have 1 level of file nesting and markdown files with headers.

ah, that's too bad. so i guess we are back to choosing a theme 😉 . i am really not a big fan of material because of the TOC on the right. below suggestions:

• materials without toc on the right
• https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes#gitbook-theme
• https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes#ivory-theme
• https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes#windmill

[po09i]

ah, that's too bad. so i guess we are back to choosing a theme 😉 . i am really not a big fan of material because of the TOC on the right. below suggestions:

Yes it's a recurring theme.. hehe

• I found a way to disable the secondary TOC here. I find it a bit annoying though not having the ability to quickly jump to a specific headers.
• Ivory looks like a bare-bone version of RTD

• I like windmill the best out of the list if we don't want a TOC on the right.

I'm not entirely satisfied though with the look so I'll keep looking.

[jcohenadad]

Ivory looks like a bare-bone version of RTD

looks beautiful, no? so far it's my best (after RTD)

windmill: i find it cool, but i find the "windmill effect" (animations on the toc) a bit distracting

[po09i]

looks beautiful, no? so far it's my best (after RTD)

I don't have a strong preference for windmill. We can go for the Ivory theme if I fix the search bar not working problem on that theme.