Use mike for versioned documentation

.github/workflows/publish-docs.yml

@@ -36,28 +36,30 @@ jobs:
           version="${{ (inputs.plan != '' && fromJson(inputs.plan).announcement_tag) || inputs.ref }}"
           # if version is missing, exit with error
           if [[ -z "$version" ]]; then
-          echo "Can't build docs without a version."
+            echo "Can't build docs without a version."
-          exit 1
+            exit 1
           fi
 
           # Use version as display name for now
           display_name="$version"
 
-          echo "version=$version" >> $GITHUB_ENV
+          # Extract the major and minor part of the version for the docs
-          echo "display_name=$display_name" >> $GITHUB_ENV
+          docs_version="$(echo -n "$version" | cut -d "." -f 1-2)"
+
+          echo "version=$version" >> "$GITHUB_ENV"
+          echo "docs_version=$docs_version" >> "$GITHUB_ENV"
+          echo "display_name=$display_name" >> "$GITHUB_ENV"
 
       - name: "Set branch name"
         run: |
-          version="${{ env.version }}"
-          display_name="${{ env.display_name }}"
           timestamp="$(date +%s)"
 
-          # create branch_display_name from display_name by replacing all
+          # Create `branch_display_name` from `display_name` by replacing all
           # characters disallowed in git branch names with hyphens
-          branch_display_name="$(echo "$display_name" | tr -c '[:alnum:]._' '-' | tr -s '-')"
+          branch_display_name="$(echo -n "$display_name" | tr -c '[:alnum:]._' '-' | tr -s '-')"
 
-          echo "branch_name=update-docs-$branch_display_name-$timestamp" >> $GITHUB_ENV
+          echo "branch_name=update-docs-$branch_display_name-$timestamp" >> "$GITHUB_ENV"
-          echo "timestamp=$timestamp" >> $GITHUB_ENV
+          echo "timestamp=$timestamp" >> "$GITHUB_ENV"
 
       - name: "Add SSH key"
         if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS == 'true' }}
@@ -70,7 +72,7 @@ jobs:
 
       - uses: Swatinem/rust-cache@v2
 
-      - name: "Install Insiders dependencies"
+      - name: "Install insiders dependencies"
         if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS == 'true' }}
         run: pip install -r docs/requirements-insiders.txt
 
@@ -78,74 +80,86 @@ jobs:
         if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS != 'true' }}
         run: pip install -r docs/requirements.txt
 
-      - name: "Copy README File"
+      - name: "Fetch docs repo"
+        run: |
+          remote_name="astral-docs"
+
+          git remote add "$remote_name" https://${{ secrets.ASTRAL_DOCS_PAT }}@github.com/astral-sh/docs.git
+          git fetch astral-docs "main:$branch_name"
+
+          echo "remote_name=$remote_name" >> "$GITHUB_ENV"
+
+      - name: "Configure git"
+        run: |
+          git config user.name "astral-docs-bot"
+          git config user.email "176161322+astral-docs-bot@users.noreply.github.com"
+
+      - name: "Transform README and generate docs"
         run: |
           python scripts/transform_readme.py --target mkdocs
           python scripts/generate_mkdocs.py
 
       - name: "Build Insiders docs"
         if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS == 'true' }}
-        run: mkdocs build --strict -f mkdocs.insiders.yml
+        run: |
+          mike deploy \
+            --remote "$remote_name" \
+            --branch "$branch_name" \
+            --message "Update ruff documentation for $version" \
+            --config-file mkdocs.insiders.yml \
+            --update-aliases \
+            --push \
+            "$docs_version" latest
 
       - name: "Build docs"
         if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS != 'true' }}
-        run: mkdocs build --strict -f mkdocs.public.yml
-
-      - name: "Clone docs repo"
         run: |
-          version="${{ env.version }}"
+          mike deploy \
-          git clone https://${{ secrets.ASTRAL_DOCS_PAT }}@github.com/astral-sh/docs.git astral-docs
+            --remote "$remote_name" \
-
+            --branch "$branch_name" \
-      - name: "Copy docs"
+            --message "Update ruff documentation for $version" \
-        run: rm -rf astral-docs/site/ruff && mkdir -p astral-docs/site && cp -r site/ruff astral-docs/site/
+            --config-file mkdocs.public.yml \
-
+            --update-aliases \
-      - name: "Commit docs"
+            --push \
-        working-directory: astral-docs
+            "$docs_version" latest
-        run: |
-          branch_name="${{ env.branch_name }}"
-
-          git config user.name "astral-docs-bot"
-          git config user.email "176161322+astral-docs-bot@users.noreply.github.com"
-
-          git checkout -b $branch_name
-          git add site/ruff
-          git commit -m "Update ruff documentation for $version"
 
       - name: "Create Pull Request"
-        working-directory: astral-docs
         env:
           GITHUB_TOKEN: ${{ secrets.ASTRAL_DOCS_PAT }}
         run: |
-          version="${{ env.version }}"
+          # Set the docs repository
-          display_name="${{ env.display_name }}"
+          astral_docs_repo="astral-sh/docs"
-          branch_name="${{ env.branch_name }}"
 
-          # set the PR title
+          # Set the PR title
           pull_request_title="Update ruff documentation for $display_name"
 
           # Delete any existing pull requests that are open for this version
-          # by checking against pull_request_title because the new PR will
+          # by checking against `pull_request_title` because the new PR will
           # supersede the old one.
-          gh pr list --state open --json title --jq '.[] | select(.title == "$pull_request_title") | .number' | \
+          gh pr list \
-            xargs -I {} gh pr close {}
+            --state open \
+            --json title,number \
+            --jq '.[] | select(.title == "$pull_request_title") | .number' \
+            --repo "$astral_docs_repo" | \
+              xargs -I {} gh pr close {}
 
-          # push the branch to GitHub
+          # Create the PR, the branch has already been pushed by `mike`
-          git push origin $branch_name
+          gh pr create --base main --head "$branch_name" \
-
-          # create the PR
-          gh pr create --base main --head $branch_name \
             --title "$pull_request_title" \
             --body "Automated documentation update for $display_name" \
-            --label "documentation"
+            --label "documentation" \
+            --repo "$astral_docs_repo"
 
-      - name: "Merge Pull Request"
+      # TODO(dhruvmanila): Uncomment once a patch and minor release are done, thus
-        if: ${{ inputs.plan != '' && !fromJson(inputs.plan).announcement_tag_is_implicit }}
+      # confirming that it works as intended
-        working-directory: astral-docs
+      #
-        env:
+      # - name: "Merge Pull Request"
-          GITHUB_TOKEN: ${{ secrets.ASTRAL_DOCS_PAT }}
+      #   if: ${{ inputs.plan != '' && !fromJson(inputs.plan).announcement_tag_is_implicit }}
-        run: |
+      #   env:
-          branch_name="${{ env.branch_name }}"
+      #     GITHUB_TOKEN: ${{ secrets.ASTRAL_DOCS_PAT }}
-          # auto-merge the PR if the build was triggered by a release. Manual builds should be reviewed by a human.
+      #   run: |
-          # give the PR a few seconds to be created before trying to auto-merge it
+      #     branch_name="${{ env.branch_name }}"
-          sleep 10
+      #     # auto-merge the PR if the build was triggered by a release. Manual builds should be reviewed by a human.
-          gh pr merge --squash $branch_name
+      #     # give the PR a few seconds to be created before trying to auto-merge it
+      #     sleep 10
+      #     gh pr merge --squash $branch_name --repo "astral-sh/docs"

mkdocs.template.yml

@@ -61,6 +61,9 @@ markdown_extensions:
 plugins:
   - search
   - typeset
+  - mike:
+      deploy_prefix: site/ruff
+      canonical_version: latest
 extra_css:
   - stylesheets/extra.css
 extra_javascript:
@@ -71,3 +74,6 @@ not_in_nav: |
 extra:
   analytics:
     provider: fathom
+  version:
+    provider: mike
+    alias: true