Primary Navigation: Increase toctree.maxdepth to 4 for Cloud and Guides #515
Conversation
This theme derives from [sphinx-basic-ng], but needs a few components from [Furo]. For example, the menu builder from Furo's `navigation.py` is made available to the HTML context via `ng_navigation_tree`. Therefore, it needs to vendorize a few styles. It can not take the whole thing, because Furo's colors currently interfere with the colors provided by the theme's styles. [Furo]: https://github.com/pradyunsg/furo [sphinx-basic-ng]: https://github.com/pradyunsg/sphinx-basic-ng
For demonstration purposes, it displays an automatically generated navigation tree, as well as the custom semi-static menu provided by the theme. The navigation tree is generated using Furo's `compute_navigation_tree`.
|
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:
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 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. |
A few sections may require more depth. Let's probe how this could make a difference.
amotl
force-pushed
the
amo/adjust-primary-nav-maxdepth
branch
from
2e71f81
to
b159169
Compare
|
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? |
amotl
force-pushed
the
matthias/first-bunch-of-ng-fixes
branch
from
8f3437c
to
c013bba
Compare
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-themeproject, because its docmentation doesn't provide any reasonable depth at all.https://crate-docs-theme--515.org.readthedocs.build/en/515/
References
Better previews and reviews are better conducted on behalf of relevant downstream projects.