docs: render captioned sidebar sections for versioned user guides#4699
Open
andygrove wants to merge 1 commit into
Open
docs: render captioned sidebar sections for versioned user guides#4699andygrove wants to merge 1 commit into
andygrove wants to merge 1 commit into
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Which issue does this PR close?
N/A. Follow-on to #4698 (0.17.0 documentation links).
Rationale for this change
The published 0.17 user guide does not render its left-sidebar navigation as captioned sections (Getting Started, What Comet Supports, Compatibility, etc.) the way the development snapshot (
latest) does. Everything is flattened under a single "User Guide" heading.The cause is in the custom sidebar template
docs/source/_templates/docs-sidebar.html. It only starts the sidebar toctree at depth 2 for pages underuser-guide/latest/. Released-version directories such asuser-guide/0.17/are not matched, so they fall back to depth 1, which roots the navigation at the parentuser-guide/index.md("User Guide" caption) and pushes the version's own captioned sub-toctrees one level deeper. Sphinx does not render:caption:for those deeper toctrees, so the section headings disappear and the entries flatten.This only began to show with 0.17 because it is the first released version whose frozen
index.rstuses the captioned multi-section layout (added in #4424, after 0.16 was branched). Versions 0.13 through 0.16 are legitimately flat.What changes are included in this PR?
Generalize the depth-2 condition in
docs/source/_templates/docs-sidebar.htmlto match any user-guide version subdirectory (latestor a numbered release like0.17) rather than onlyuser-guide/latest/. The wrapper pagesuser-guide/indexanduser-guide/older-versionsremain at depth 1 since they are only two path segments deep.How are these changes tested?
Built the docs locally and compared the rendered
user-guide/0.17/index.htmlagainstuser-guide/latest/index.html. Before the change, 0.17 rendered a single "User Guide" caption with its content attoctree-l2; after the change, 0.17 renders the six section captions with content attoctree-l1, matchinglatest. Thelatestnavigation is unchanged.