-
-
Notifications
You must be signed in to change notification settings - Fork 3.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Fix unreachable pages in sidebar by using fake headers in index pages #9989
Conversation
- Ensure most pages are reachable through the sidebar, by removing headers on pages that are mostly indexes. - This also means that some pages now have navigable headers again.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Built the docs with this and everything works!
(These can both be done in future PRs, too) |
Better to keep PRs smaller and easy to digest :) Those sound like good followup PRs. Thank you, merged! And thanks Sky for testing. |
One side effect to note is that fake headers such as But old links like this one still redirect to the page itself: https://docs.godotengine.org/en/latest/tutorials/scripting/index.html#programming-languages We can look into adding back in permalinks somehow, but even if the permalinks can't be added back in, I think this is a fine tradeoff for improved usability. |
Cherry-picked to 4.3 in #10038. |
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.