Repository navigation
[DOCS]: Version dropdown in older doc versions doesn't show newer releases #302
Description
Activity
Problem
The version dropdown in
/v0.1.6/(and any future older versions) shows only
the versions that existed at the time that version was built. So/v0.1.6/
does not show v0.2.0 in its dropdown — a user landing there has no way to
navigate to the latest docs without editing the URL.Root cause
The dropdown is rendered into static HTML by Sphinx at build time, from
docs/versions.jsonat whatever commit is being built. Older versions were
built before newer ones existed, so theirversions.jsonsnapshots are
incomplete.Options
- A. Manually rebuild older versions — one-off fix per version. Fiddly.
- B. Rebuild all previous tags on every release — clean but adds build time.
- C. Runtime dropdown via JS — fetch
versions.jsonat page load rather
than baking it in. Requires all versions to have the JS, so a one-off
rebuild of all existing versions is needed to bootstrap. This is what
ReadTheDocs and mkdocs-material do.
Recommendation
Adopt Option C (runtime dropdown) once the alpha has a few more releases so
the one-off rebuild covers more versions in one go. In the meantime, users
landing on old versions can strip the/vX.Y.Z/from the URL.Related
- Issue [DOCUMENTATION]: Streamline release notes generation (partial automation) #300 (release notes automation) — similar "infrastructure vs
immediate need" trade-off docs.yml— where the fix would livedocs/_static/— where the JS snippet would go
ie. v0.6.0 dropdown sphinx docs doesnt show 0.2.0 release onwards