Change sidebar navigation depth from 4 to 5

[tetrapod00]

In #9989 and followups, we fixed pages that were unreachable from the sidebar by using fake headers within some index pages. Even with that change, the limited nesting of the sidebar requires us to perform some awkward organization to ensure that every page is reachable, and occasionally avoid semantic organization within pages and sections to avoid too deep nesting. Many pages, specificially those within the Scripting, Particle systems (3D), and Engine development sections, only have pages appear in the sidebar, but not the sub-page headers which are useful for navigation.

I propose increasing the allowed navigation depth at the RTD theme level, along with our existing organization principles and use of non-semantic headers, to allow more pages to have visible subpage headers. This will also give us some breathing room for the inevitable deeper nesting that is always desired to better organize content (see #10617, for example).

Examples

Before	After

Downsides

Visually busy sidebar

While adding the subpage headers to the sidebar aids navigation for the most deeply nested pages, it does cause a busy-looking sidebar for less deeply nested pages since subheaders within a page now appear in the sidebar. In some cases this is desired, as in the Shading language example above. In other cases it might be unneeded visual noise.

I don't think that Sphinx gives us the tools to control this more finely, for example only ever showing a single sub-page level of nesting in the sidebar, but I'll look into it along with further testing.

Performance

The docs for collapse_navigation which we also use mention:

Setting collapse_navigation to False and using a high value for navigation_depth on projects with many files and a deep file structure can cause long compilation times and can result in HTML files that are significantly larger in file size.

I think we may already qualify for those long compilation times and large HTML files, even with 4-deep nesting 🙂.

Basic testing:
4-deep nesting (current): 1.89 GB folder for html build.
5-deep nesting (this PR): 2.12 GB folder for html build.

On the CI, this PR takes ~2:00 to build, which is about the same as a sample of other PRs. Maybe it takes a second or two longer. But the CI doesn't build HTML.

I need to do some more rigorous testing on compile times and size of the build.

See also

#8535 argues against having subpage headers visible in the sidebar. I disagree, but it's useful context.
#8792 for the unreachable pages.
#5701 for the desire to have some TOC or navigation for long pages.