Add documentation publishing workflow to standalone repo (#5081)

## Summary

This approach is based on https://github.com/PrefectHQ/docs. Rather than
publishing docs in the uv repo, we push to an independent repo that's
used solely to house the docs. In Prefect's case, this allows them to
publish versioned documentation (we should do that too). For us, though,
the benefit is that we can publish the Ruff and uv docs as a single site
(docs.astral.sh).

Prefect clones the source repo and builds the documentation from the
`docs` repo (i.e., the action runs in the `docs` repo). In our case,
I've instead set it up such that the action runs in `uv` (and later in
`ruff` too), clones the `docs` repo, and puts up a PR in that separate
repo. Because of these requirements, we have to use a PAT rather than a
deploy key (as PATs cannot do GitHub-specific things like create PRs --
they can only operate over the Git CLI).

See: https://github.com/astral-sh/docs/pull/2.

.github/workflows/publish-docs.yml

@@ -11,40 +11,119 @@ on:
         description: "The commit SHA, tag, or branch to publish. Uses the default branch if not specified."
         default: ""
         type: string
+  workflow_call:
+    inputs:
+      plan:
+        required: true
+        type: string
 
 jobs:
   mkdocs:
     runs-on: ubuntu-latest
     env:
-      CF_API_TOKEN_EXISTS: ${{ secrets.CF_API_TOKEN != '' }}
       MKDOCS_INSIDERS_SSH_KEY_EXISTS: ${{ secrets.MKDOCS_INSIDERS_SSH_KEY != '' }}
     steps:
       - uses: actions/checkout@v4
         with:
           ref: ${{ inputs.ref }}
+
       - uses: actions/setup-python@v5
+        with:
+          python-version: 3.12
+
+      - name: "Set docs version"
+        run: |
+          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."
+          exit 1
+          fi
+
+          # Use version as display name for now
+          display_name="$version"
+
+          echo "version=$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
+          # characters disallowed in git branch names with hyphens
+          branch_display_name="$(echo "$display_name" | tr -c '[:alnum:]._' '-' | tr -s '-')"
+
+          echo "branch_name=update-docs-$branch_display_name-$timestamp" >> $GITHUB_ENV
+          echo "timestamp=$timestamp" >> $GITHUB_ENV
+
       - name: "Add SSH key"
         if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS == 'true' }}
         uses: webfactory/ssh-agent@v0.9.0
         with:
           ssh-private-key: ${{ secrets.MKDOCS_INSIDERS_SSH_KEY }}
+
       - name: "Install Insiders dependencies"
         if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS == 'true' }}
         run: pip install -r docs/requirements-insiders.txt
+
       - name: "Install dependencies"
         if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS != 'true' }}
         run: pip install -r docs/requirements.txt
+
       - name: "Build Insiders docs"
         if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS == 'true' }}
         run: mkdocs build --strict -f mkdocs.insiders.yml
+
       - name: "Build docs"
         if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS != 'true' }}
         run: mkdocs build --strict -f mkdocs.public.yml
-      - name: "Deploy to Cloudflare Pages"
+
-        if: ${{ env.CF_API_TOKEN_EXISTS == 'true' }}
+      - name: "Clone repo"
-        uses: cloudflare/wrangler-action@v3.7.0
+        run: |
-        with:
+          version="${{ env.version }}"
-          apiToken: ${{ secrets.CF_API_TOKEN }}
+          git clone https://${{ secrets.ASTRAL_DOCS_PAT }}@github.com/astral-sh/docs.git astral-docs
-          accountId: ${{ secrets.CF_ACCOUNT_ID }}
+
-          # `github.head_ref` is only set during pull requests and for manual runs or tags we use `main` to deploy to production
+      - name: "Copy docs"
-          command: pages deploy site --project-name=uv-docs --branch ${{ github.head_ref || 'main' }} --commit-hash ${GITHUB_SHA}
+        run: rm -rf astral-docs/docs/uv && mkdir -p astral-docs/docs && cp -r docs/uv astral-docs/docs/
+
+      - name: "Commit docs"
+        working-directory: astral-docs
+        run: |
+          branch_name="${{ env.branch_name }}"
+
+          git config user.name "$GITHUB_ACTOR"
+          git config user.email "$GITHUB_ACTOR@users.noreply.github.com"
+
+          git checkout -b $branch_name
+          git add docs/uv
+          git commit -m "Update uv documentation for $version"
+
+      - name: "Create Pull Request"
+        working-directory: astral-docs
+        env:
+          GITHUB_TOKEN: ${{ secrets.ASTRAL_DOCS_PAT }}
+        run: |
+          version="${{ env.version }}"
+          display_name="${{ env.display_name }}"
+          branch_name="${{ env.branch_name }}"
+
+          # set the PR title
+          pull_request_title="Update 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
+          # supersede the old one.
+          gh pr list --state open --json title --jq '.[] | select(.title == "$pull_request_title") | .number' | \
+            xargs -I {} gh pr close {}
+
+          # push the branch to GitHub
+          git push origin $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"