Fix unreachable pages in sidebar by using fake headers in index pages #9989
+6
−12
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Fixes some cases of #8792
May mitigate or fix #8567
May mitigate or fix #8566
Fixes #9133
Ensures that most pages are reachable through the sidebar, by replacing real semantic headers with fake headers on index pages. As a side effect, this also means that some pages now have navigable section headers again.
There are many pages which do not show up in the sidebar (listed in #8792). It's especially bad on the scripting pages, which are used often by end users. The contributing pages are a bit less of a problem, because they are referenced less often and only by contributors.
Any header will show up in the navigation sidebar. Currently, there is a maximum depth of 5 in the navigation sidebar. Currently, there are several index pages which serve as empty "table of contents" pages, but which use headers.
The solution I arrived at is to replace the semantic headers in these pages with a fake header, using the
.. rubric::
syntax. I used this hack. I am not a sphinx, RTD, or reStructuredText expert. I hacked this together because using the docs has become actively annoying. If there's a less hacky way to solve this, I'd love to hear it.If using
rubric
is the right solution, I think the current rubric styling looks okay, but it's also possible to make custom styles to match the header styles.Visual summary of changes:
I don't know the technical reason for the current nesting limit of 5. Even if that limit was increased, we would not be free to use as many headers as we wanted - this problem of deep nesting would show up again sooner or later. Note that even with this PR, some pages get to have section headers in the sidebar, and some only have a title.