docs: collapse archived user guide versions behind a single Older Versions page#4426
Open
andygrove wants to merge 1 commit into
Open
docs: collapse archived user guide versions behind a single Older Versions page#4426andygrove wants to merge 1 commit into
andygrove wants to merge 1 commit into
Conversation
…sions page The user guide sidebar listed five versions inline (snapshot plus four release branches), which is noisy when most readers want the latest stable release. Replace the five-entry toctree with three entries: the current stable, the development snapshot, and a single Older Versions link. The new older-versions page hosts the toctree that registers the archived release branches, so Sphinx still resolves them without warnings. Closes apache#4425
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?
Closes #4425.
Rationale for this change
The user guide sidebar listed all five published versions inline (one snapshot plus four release branches). For most readers that list is noise: nearly everyone wants the latest stable release, the development snapshot is occasionally useful, and the archived versions are rarely consulted. The issue describes the list as "quite annoying" and asks for the current stable to be the default, with the snapshot and older versions tucked away.
A pydata-sphinx-theme version dropdown was considered but rejected: it assumes one Sphinx build per version at distinct URL prefixes, while Comet ships a single combined build with versions in subdirectories. Adopting the dropdown without restructuring the build would be cosmetic only and would not remove the toctree clutter. Restructuring to one build per version is a separate, larger project.
What changes are included in this PR?
docs/source/user-guide/index.mdwith three entries:0.16.x (current),Development Snapshot, andOlder Versions. Refresh the body copy to point readers at the current stable as the default.docs/source/user-guide/older-versions.md, a small page whose own toctree registers the archived versions (0.15.x, 0.14.x, 0.13.x). This keeps Sphinx warning-free while collapsing the archives behind a single sidebar entry.No changes to
generate-versions.pyor the build script: the existing release-branch cloning andlatest_released_version/previous_versionssplit already match the "one current, rest archived" model, and the new index just consumes those generated directories.Sidebar before vs after, under "User Guide":
How are these changes tested?
Verified locally by running
sphinx-buildagainst a copy ofdocs/sourcewith mock versioned directories. The build succeeds with no structural warnings, the User Guide sidebar shows exactly the three expected entries, and the Older Versions page lists working links to 0.15.x / 0.14.x / 0.13.x. CI will exercise the fulldocs/build.shpath.