andygrove opened a new pull request, #4699:
URL: https://github.com/apache/datafusion-comet/pull/4699
## 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.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
