crate-docs-theme
crate-docs-theme copied to clipboard
crate
Primary Navigation: Increase toctree.maxdepth to 4 for Cloud and Guides
Thoughts
A few sections may require more depth. Let's probe how this could make a difference for Cloud and Guides.
Preview
Not much can be inspected by looking at the preview rendering of the crate-docs-theme project, because its docmentation doesn't provide any reasonable depth at all.
https://crate-docs-theme--515.org.readthedocs.build/en/515/
Release 0.34.0.dev5
https://pypi.org/project/crate-docs-theme/0.34.0.dev5/
References
Better previews and reviews are better conducted on behalf of relevant downstream projects.
- https://github.com/crate/cloud-docs/pull/79
- https://github.com/crate/cratedb-guide/pull/112
Hello,
In general im for more depth. But in some examples it can be a bit confusing, at least to me. Like in cratedb-guide#112
e.g. https://cratedb-guide--112.org.readthedocs.build/performance/inserts/methods.html
The additional items in primary navigation aren't pages but headers/titles. So it's showing the same thing as the right-hand menu, but then lacking the depth for h2 headers. Not sure where that leaves us.
If the toctree would expand into pages instead of same-page titles, I guess those headline titles would be displayed there. So, it gives what it advertises: More depth in general. How you design and shape it on the leaf node level is probably still up to the author.
In general, both things are possible:
- At https://cratedb-guide--112.org.readthedocs.build/getting-started.html for example, primary navigation items are originating from h2 and nested headlines of that very page, while
- at https://cratedb-guide--112.org.readthedocs.build/feature/ ff., and elsewhere, it is the h1 level headlines of actual other pages, right.
Increasing the maxdepth does not change anything to that, it just provides more legroom for both variants.
Right, I know that it happening has nothing to do with this change.
I meant this will, I think, lead to variant you mention first being more visible, which is unexpected to me if the menu is built primary to display links to pages.
It's really just a proposal to use at your disposal. I can easily just NOT adjust this setting for Cloud Docs.
I meant this will, I think, lead to variant you mention first being more visible, which is unexpected to me if the menu is built primary to display links to pages.
I hear you, but in general, the primary navigation can be used for anything. It doesn't have to be "primarily built to navigate to pages". I mean, it all depends on the corresponding subtree at hand, and can be different from page to page.
NB: Well, not for anything yet. The linktree directive will improve the situation in regard to what can be plucked into primary navigation, beyond project-local toctree items.
What do you think, @proddata? I will apply maxdepth 4 to CrateDB Guide. Do you also want it for CrateDB Cloud Docs, or better not?
The relevant commit a750f880 has been included into GH-390, and will make it into the next release when there are no other objections about it.