uv/.github/workflows/publish-docs.yml

# Publish the uv documentation.
#
# Assumed to run as a subworkflow of .github/workflows/release.yml; specifically, as a post-announce
# job within `cargo-dist`.
name: mkdocs

on:
  workflow_dispatch:
    inputs:
      ref:
        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

permissions: {}

jobs:
  mkdocs:
    environment:
      name: release
    runs-on: ubuntu-latest
    env:
      VERSION: ${{ (inputs.plan != '' && fromJson(inputs.plan).announcement_tag) || inputs.ref }}
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          ref: ${{ inputs.ref }}
          fetch-depth: 0
          persist-credentials: false

      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
        with:
          python-version: 3.12

      - uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1

      - name: "Generate reference documentation"
        run: |
          cargo dev generate-options-reference
          cargo dev generate-cli-reference
          cargo dev generate-env-vars-reference

      - name: "Set docs display name"
        run: |
          version="${VERSION}"
          # if version is missing, use 'latest'
          if [ -z "$version" ]; then
            echo "Using 'latest' as version"
            version="latest"
          fi

          # Use version as display name for now
          display_name="$version"

          echo "DISPLAY_NAME=$display_name" >> $GITHUB_ENV

      - name: "Set branch name"
        run: |
          version="${VERSION}"
          display_name="${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: "Install uv"
        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
        with:
          version: "0.11.2"

      - name: "Build docs"
        run: uv run --only-group docs mkdocs build --strict -f mkdocs.yml

      - name: "Clone docs repo"
        run: |
          version="${VERSION}"
          git clone https://${ASTRAL_DOCS_PAT}@github.com/astral-sh/docs.git astral-docs
        env:
          ASTRAL_DOCS_PAT: ${{ secrets.ASTRAL_DOCS_PAT }}

      - name: "Copy docs"
        run: rm -rf astral-docs/site/uv && mkdir -p astral-docs/site && cp -r site/uv astral-docs/site/

      - name: "Commit docs"
        working-directory: astral-docs
        run: |
          branch_name="${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/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="${VERSION}"
          display_name="${DISPLAY_NAME}"
          branch_name="${BRANCH_NAME}"

          # set the PR title
          pull_request_title="Update uv 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"

      - name: "Merge Pull Request"
        if: ${{ inputs.plan != '' && !fromJson(inputs.plan).announcement_tag_is_implicit }}
        working-directory: astral-docs
        env:
          GITHUB_TOKEN: ${{ secrets.ASTRAL_DOCS_PAT }}
        run: |
          branch_name="${BRANCH_NAME}"

          # auto-merge the PR if the build was triggered by a release. Manual builds should be reviewed by a human.
          # give the PR a few seconds to be created before trying to auto-merge it
          sleep 10
          gh pr merge --squash $branch_name