manual_version_docs.yaml

name: Version docs

on:
  # Runs when manually triggered from the GitHub UI.
  workflow_dispatch:
    inputs:
      ref:
        description: Git ref to checkout (branch, tag, or SHA). Defaults to the default branch.
        required: false
        type: string
        default: ""

  # Runs when invoked by another workflow.
  workflow_call:
    inputs:
      ref:
        description: Git ref to checkout (branch, tag, or SHA)
        required: true
        type: string
    outputs:
      version_docs_commitish:
        description: The commit SHA of the versioned docs commit
        value: ${{ jobs.version_docs.outputs.version_docs_commitish }}

concurrency:
  group: version-docs
  cancel-in-progress: false

permissions:
  contents: read

env:
  NODE_VERSION: 22
  PYTHON_VERSION: "3.14"

jobs:
  version_docs:
    name: Version docs
    runs-on: ubuntu-latest
    outputs:
      version_docs_commitish: ${{ steps.resolve_commitish.outputs.commitish }}
    permissions:
      contents: write

    steps:
      - name: Determine checkout ref
        id: resolve_ref
        run: |
          REF="${{ inputs.ref }}"
          if [[ -z "$REF" ]]; then
            REF="${{ github.event.repository.default_branch }}"
          fi
          echo "ref=$REF" >> "$GITHUB_OUTPUT"

      - name: Checkout repository
        uses: actions/checkout@v6
        with:
          token: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
          ref: ${{ steps.resolve_ref.outputs.ref }}

      - name: Set up Node
        uses: actions/setup-node@v6
        with:
          node-version: ${{ env.NODE_VERSION }}

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: ${{ env.PYTHON_VERSION }}

      - name: Set up uv package manager
        uses: astral-sh/setup-uv@v7
        with:
          python-version: ${{ env.PYTHON_VERSION }}

      - name: Install Python dependencies
        run: uv run poe install-dev

      - name: Snapshot the current version
        id: snapshot
        run: |
          cd website
          corepack enable
          yarn install

          # Extract version from pyproject.toml.
          FULL_VERSION="$(uv version --short)"
          MAJOR_MINOR_VERSION="$(echo "$FULL_VERSION" | cut -d. -f1-2)"
          MAJOR_VERSION="$(echo "$FULL_VERSION" | cut -d. -f1)"
          echo "version=$FULL_VERSION" >> "$GITHUB_OUTPUT"
          echo "Version: $FULL_VERSION, Major.Minor: $MAJOR_MINOR_VERSION, Major: $MAJOR_VERSION"

          # Find the existing version for this major in versions.json (if any).
          if [[ -f versions.json ]]; then
            OLD_VERSION="$(jq -r --arg major "$MAJOR_VERSION" '.[] | select(startswith($major + "."))' versions.json | head -1)"
          else
            OLD_VERSION=""
            echo "[]" > versions.json
          fi

          # Remove only the specific old version for this major (if found).
          if [[ -n "$OLD_VERSION" ]]; then
            echo "Removing old version $OLD_VERSION for major $MAJOR_VERSION"
            rm -rf "versioned_docs/version-${OLD_VERSION}"
            rm -f "versioned_sidebars/version-${OLD_VERSION}-sidebars.json"
            jq --arg old "$OLD_VERSION" '[.[] | select(. != $old)]' versions.json > tmp.json && mv tmp.json versions.json
          else
            echo "No existing version found for major $MAJOR_VERSION, nothing to remove"
          fi

          # Build API reference and create Docusaurus version snapshots.
          bash build_api_reference.sh
          uv run npx docusaurus docs:version "$MAJOR_MINOR_VERSION"
          uv run npx docusaurus api:version "$MAJOR_MINOR_VERSION"

      - name: Commit and push versioned docs
        id: commit_versioned_docs
        uses: EndBug/add-and-commit@v10
        with:
          add: website/versioned_docs website/versioned_sidebars website/versions.json
          message: "docs: Version docs for v${{ steps.snapshot.outputs.version }} [skip ci]"
          default_author: github_actions

      - name: Resolve output commitish
        id: resolve_commitish
        run: |
          SHA="${{ steps.commit_versioned_docs.outputs.commit_long_sha }}"
          if [[ -z "$SHA" ]]; then
            SHA="$(git rev-parse HEAD)"
          fi
          echo "commitish=$SHA" >> "$GITHUB_OUTPUT"