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

    area: compatibilityCompatibility, availability, legacy support, and cross-version behavior.area: docsDocumentation area label.area: toolingDeveloper tooling, package manifests, Tuist, scripts, formatting, or release tooling.type: docsDocumentation, README, guides, or package index metadata.type: featureNew API, behavior, platform support, or user-facing capability.

    Type

    No type
    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