Skip to content
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

Merged
merged 1 commit into from
Sep 28, 2024

Conversation

tetrapod00
Copy link
Contributor

@tetrapod00 tetrapod00 commented Sep 23, 2024

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:

Page Master This PR
GDScript exported properties gdscript exported master firefox_XVs3eaDzdk
C# Signals c# signals master firefox_k2JFaZhM4B
Building from Source firefox_MM6ydYbh10 building source pr
Engine core and modules firefox_ROdbWjTOT5 engine core pr

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.

- 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.
@Calinou Calinou added bug content:website Issues related to adding website features and fixing bugs, whether on the front or back-end content:organization Issues and PRs related to reorganizing the content and removed content:website Issues related to adding website features and fixing bugs, whether on the front or back-end labels Sep 23, 2024
@skyace65 skyace65 added the content:website Issues related to adding website features and fixing bugs, whether on the front or back-end label Sep 27, 2024
Copy link
Contributor

@skyace65 skyace65 left a 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!

@tetrapod00
Copy link
Contributor Author

tetrapod00 commented Sep 27, 2024

  1. Should the custom styles for rubric be added to match existing header styles?
  2. There is one more large set of hidden pages, the children of https://docs.godotengine.org/en/stable/tutorials/3d/particles/index.html. I didn't fix those yet because the index page also has significant actual info, so the fix might be more complex. Should I try to fix that in this PR too?

(These can both be done in future PRs, too)

@mhilbrunner mhilbrunner merged commit ddb3df4 into godotengine:master Sep 28, 2024
1 check passed
@mhilbrunner
Copy link
Member

Better to keep PRs smaller and easy to digest :) Those sound like good followup PRs. Thank you, merged! And thanks Sky for testing.

@tetrapod00 tetrapod00 deleted the sidebar branch September 28, 2024 17:49
@tetrapod00
Copy link
Contributor Author

tetrapod00 commented Sep 28, 2024

One side effect to note is that fake headers such as Programming Languages no longer have a copyable permalink:
firefox_wCcl8ykuHw

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug cherrypick:4.3 content:organization Issues and PRs related to reorganizing the content content:website Issues related to adding website features and fixing bugs, whether on the front or back-end
Projects
None yet
4 participants