Skip to content

docs: collapse archived user guide versions behind a single Older Versions page#4426

Open
andygrove wants to merge 1 commit into
apache:mainfrom
andygrove:user-guide-versions-nav-4425
Open

docs: collapse archived user guide versions behind a single Older Versions page#4426
andygrove wants to merge 1 commit into
apache:mainfrom
andygrove:user-guide-versions-nav-4425

Conversation

@andygrove
Copy link
Copy Markdown
Member

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?

  • Replace the five-entry user guide toctree in docs/source/user-guide/index.md with three entries: 0.16.x (current), Development Snapshot, and Older Versions. Refresh the body copy to point readers at the current stable as the default.
  • Add 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.py or the build script: the existing release-branch cloning and latest_released_version / previous_versions split already match the "one current, rest archived" model, and the new index just consumes those generated directories.

Sidebar before vs after, under "User Guide":

Before:                          After:
0.17.0-SNAPSHOT                  0.16.x (current)
0.16.x                           Development Snapshot
0.15.x                           Older Versions
0.14.x
0.13.x

How are these changes tested?

Verified locally by running sphinx-build against a copy of docs/source with 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 full docs/build.sh path.

…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
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.

Improve switching between Comet versions of user guide

1 participant