Skip to content

Add versioned documentation support for releases #708

@Kyle-Ye

Description

@Kyle-Ye

Description

Currently, the documentation deployment script (update-gh-pages-documentation.sh) publishes documentation without version tracking. After each release, we should be able to generate and maintain documentation for specific versions.

Proposed Solution

Add a --version parameter to the documentation update script that:

  1. Accepts a version identifier (e.g., 0.1.0, 1.0.0)
  2. Organizes documentation output by version in the gh-pages branch
  3. Maintains a version selector or index page to navigate between different versions

Suggested Implementation

Script Changes

  • Add --version VERSION parameter to Scripts/update-gh-pages-documentation.sh
  • Modify the deployment path to include version: gh-pages/docs/{version}/
  • Generate or update an index page listing all available versions
  • Optionally create a latest symlink or redirect to the most recent version

Workflow

After each tag release, GitHub workflow should automatically run the following command

./Scripts/update-gh-pages-documentation.sh --version 0.1.0

Directory Structure

gh-pages/
├── docs/
│   ├── v0.1.0/
│   ├── v0.2.0/
│   ├── latest/ (symlink or copy)
│   └── index.html (version selector)
└── .nojekyll

Benefits

  • Users can reference documentation for specific versions they're using
  • Maintains historical documentation for older releases
  • Improves documentation discoverability and usability
  • Aligns with common documentation practices (e.g., Swift.org, Vapor, etc.)

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions