Primary Navigation: Increase toctree.maxdepth to 4 for Cloud and Guides

[amotl]

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/

References

Better previews and reviews are better conducted on behalf of relevant downstream projects.

• Theme: Update to crate-docs-theme==0.34.0.dev6 cloud-docs#79
• Theme: Update to crate-docs-theme==0.34.0.dev6 cratedb-guide#112

[matkuliak]

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.

[amotl]

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.

[matkuliak]

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.

[amotl]

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.

[amotl]

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]

The relevant commit a750f88 has been included into GH-390, and will make it into the next release when there are no other objections about it.