Skip to content

docs: render captioned sidebar sections for versioned user guides#4699

Open
andygrove wants to merge 1 commit into
apache:mainfrom
andygrove:docs/sidebar-versioned-sections
Open

docs: render captioned sidebar sections for versioned user guides#4699
andygrove wants to merge 1 commit into
apache:mainfrom
andygrove:docs/sidebar-versioned-sections

Conversation

@andygrove

Copy link
Copy Markdown
Member

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 under user-guide/latest/. Released-version directories such as user-guide/0.17/ are not matched, so they fall back to depth 1, which roots the navigation at the parent user-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.rst uses 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.html to match any user-guide version subdirectory (latest or a numbered release like 0.17) rather than only user-guide/latest/. The wrapper pages user-guide/index and user-guide/older-versions remain 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.html against user-guide/latest/index.html. Before the change, 0.17 rendered a single "User Guide" caption with its content at toctree-l2; after the change, 0.17 renders the six section captions with content at toctree-l1, matching latest. The latest navigation is unchanged.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant