User Guide Table of Contents might be too shallow

[swzCuroverse]

Table of Contents only show 1 level down hiding important sections in Workflow and other sections. I would suggest showing 1 level down so people are more easily find sections about scatter, conditionals, etc.

[kinow]

To customize the depth of the table of contents:

1. Search for {toctree}. This might appear in Markdown pages, rendered by Sphinx. The {toctree} directive supports a maxdepth parameter, e.g. https://github.com/raw/common-workflow-language/user_guide/main/src/index.md

Play with that value, running make watch locally (after installing dependencies) or using the ReadTheDocs preview, until you get the desired output.

2. The PyData Sphinx theme, that we use in the User Guide, uses the Sphinx table of contents of the landing page to create the navigation menus (top and left). You can customize these in the src/conf.py.

From what I remember, these settings are under the html options for the theme, likely these:

user_guide/src/conf.py

Lines 188 to 189 in 3ed85b8

	"show_nav_level": 2,
	"navigation_depth": 2,

Or refer to the https://github.com/pydata/pydata-sphinx-theme theme docs for more. Again, change it, preview, and customize as needed. If something goes wrong:

• Check the pydata repository for issues/questions/pull requests for similar issues. That theme has a lot of other users like JupyterHub and Pandas (although they may have further customized it or replaced by another existing theme).
• Destroy your virtual environment folder and the build directory. Sometimes you get weird behavior after changing too many files locally, or when you update dependencies that export scripts, etc. Always worth to start from scratch as it should take ~1 minute.

-Bruno

[swzCuroverse]

Thank you Bruno

[smyja]

To customize the depth of the table of contents:

1. Search for {toctree}. This might appear in Markdown pages, rendered by Sphinx. The {toctree} directive supports a maxdepth parameter, e.g. https://github.com/raw/common-workflow-language/user_guide/main/src/index.md

Play with that value, running make watch locally (after installing dependencies) or using the ReadTheDocs preview, until you get the desired output.

2. The PyData Sphinx theme, that we use in the User Guide, uses the Sphinx table of contents of the landing page to create the navigation menus (top and left). You can customize these in the src/conf.py.

From what I remember, these settings are under the html options for the theme, likely these:

user_guide/src/conf.py

Lines 188 to 189 in 3ed85b8

	"show_nav_level": 2,
	"navigation_depth": 2,

Or refer to the https://github.com/pydata/pydata-sphinx-theme theme docs for more. Again, change it, preview, and customize as needed. If something goes wrong:

• Check the pydata repository for issues/questions/pull requests for similar issues. That theme has a lot of other users like JupyterHub and Pandas (although they may have further customized it or replaced by another existing theme).
• Destroy your virtual environment folder and the build directory. Sometimes you get weird behavior after changing too many files locally, or when you update dependencies that export scripts, etc. Always worth to start from scratch as it should take ~1 minute.

-Bruno

Is it the topics table of content this issue is referring to? https://www.commonwl.org/user_guide/topics/index.html
The sub headers show on the right when you click the topic. There's no option to show the subheaders on the left.

You can only show sub pages on the left sidebar of a topic. I haven't seen any theme that can do that. I have played around different options you mentioned and they didn't show the subheaders on the left sidebar.
Read more here.
pydata/pydata-sphinx-theme#1007 (comment)
@kinow

[smyja]

Any update? @swzCuroverse @kinow

[kinow]

Nothing from me, sorry. Haven't worked on this issue since my last message. Someone will need to choose the depth level of each table of contents (which are used to create menus in Sphinx) and investigate how to reflect the desired configuration in Sphinx conf.py.