Skip to content

S23.07: Landing page and version switcher #253

Description

@DavidCozens

Parent epic: #246

Goal

Give users a way to discover and switch between published versions of
the docs.

Tasks

  • Add a small landing page at the root of gh-pages that:
    • Lists all available versions.
    • Links to each.
    • Highlights /latest/.
    • Makes clear which entry is main (development, may change) vs
      tagged stable releases.
  • Configure Sphinx's version-aware navigation so that within any
    given version
    , the user can see they're on v1.0.0 (or main)
    and switch to other versions.
  • Mechanism: a generated versions.json at the root of gh-pages,
    consumed by a small JS snippet in the theme footer (or theme-native
    version selector if furo / sphinx-book-theme provides one
    natively). Keep it simple — no need for anything sophisticated.
  • The landing page and versions.json must be regenerated on each
    release (S23.05) and on each push to main (S23.04) so they stay in
    sync with what's actually published.
  • Update DEVLOG.md.

Done when

  • Visiting the Pages root shows a landing page listing all versions.
  • /latest/ is visually highlighted and labelled as such.
  • main is visibly distinguished from tagged versions.
  • From any version, users can switch to any other version via the
    version selector.
  • versions.json is regenerated by both the S23.04 and S23.05
    workflows.

Metadata

Metadata

Assignees

No one assigned

    Labels

    storyStory issue

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions