ci: Extract docs versioning into reusable manual_version_docs.yaml workflow

.github/workflows/manual_release_stable.yaml

@@ -105,68 +105,12 @@ jobs:
   version_docs:
     name: Version docs
     needs: [release_prepare, changelog_update, pypi_publish]
-    runs-on: ubuntu-latest
-    outputs:
-      version_docs_commitish: ${{ steps.commit_versioned_docs.outputs.commit_long_sha }}
     permissions:
       contents: write
-    env:
-      NODE_VERSION: 22
-      PYTHON_VERSION: 3.14
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v6
-        with:
-          token: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
-          ref: ${{ needs.changelog_update.outputs.changelog_commitish }}
-
-      - 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: Install website dependencies
-        run: |
-          cd website
-          corepack enable
-          yarn install
-
-      - name: Snapshot the current version
-        run: |
-          cd website
-          VERSION="$(python -c "import tomllib, pathlib; print(tomllib.loads(pathlib.Path('../pyproject.toml').read_text())['project']['version'])")"
-          MAJOR_MINOR="$(echo "$VERSION" | cut -d. -f1-2)"
-          export MAJOR_MINOR
-          # Remove existing version if present (patch releases override)
-          rm -rf "versioned_docs/version-${MAJOR_MINOR}"
-          rm -rf "versioned_sidebars/version-${MAJOR_MINOR}-sidebars.json"
-          jq 'map(select(. != env.MAJOR_MINOR))' versions.json > tmp.json && mv tmp.json versions.json
-          # Build API reference and create version snapshots
-          bash build_api_reference.sh
-          npx docusaurus docs:version "$MAJOR_MINOR"
-          npx docusaurus api:version "$MAJOR_MINOR"
-
-      - 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 ${{ needs.release_prepare.outputs.version_number }} docs [skip ci]"
-          default_author: github_actions
+    uses: ./.github/workflows/manual_version_docs.yaml
+    with:
+      ref: ${{ needs.changelog_update.outputs.changelog_commitish }}
+    secrets: inherit
 
   doc_release:
     name: Doc release

.github/workflows/manual_version_docs.yaml

@@ -0,0 +1,132 @@
+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
+        env:
+          INPUT_REF: ${{ inputs.ref }}
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        run: |
+          REF="${INPUT_REF:-$DEFAULT_BRANCH}"
+          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 versions for this major in versions.json (if any).
+          if [[ -f versions.json ]]; then
+            OLD_VERSIONS="$(jq -r --arg major "$MAJOR_VERSION" '.[] | select(startswith($major + "."))' versions.json)"
+          else
+            OLD_VERSIONS=""
+            echo "[]" > versions.json
+          fi
+
+          # Remove all old versions for this major (if found).
+          if [[ -n "$OLD_VERSIONS" ]]; then
+            while IFS= read -r OLD_VERSION; do
+              [[ -z "$OLD_VERSION" ]] && continue
+              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"
+            done <<< "$OLD_VERSIONS"
+            jq --arg major "$MAJOR_VERSION" 'map(select(startswith($major + ".") | not))' versions.json > tmp.json && mv tmp.json versions.json
+          else
+            echo "No existing versions 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
+        env:
+          COMMIT_SHA: ${{ steps.commit_versioned_docs.outputs.commit_long_sha }}
+        run: |
+          echo "commitish=${COMMIT_SHA:-$(git rev-parse HEAD)}" >> "$GITHUB_OUTPUT"

.gitignore

@@ -64,6 +64,7 @@ Session.vim
 # Docs
 docs/changelog.md
 website/versioned_docs/*/changelog.md
+website/versioned_docs/*/pyproject.toml
 
 # Website build artifacts, node dependencies
 website/build