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:
    runs-on: ubuntu-latest
    env:
      VERSION: ${{ (inputs.plan != '' && fromJson(inputs.plan).announcement_tag) || inputs.ref }}
      MKDOCS_INSIDERS_SSH_KEY_EXISTS: ${{ secrets.MKDOCS_INSIDERS_SSH_KEY != '' }}
    steps:
      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
        with:
          ref: ${{ inputs.ref }}
          fetch-depth: 0
          persist-credentials: false

      - uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
        with:
          python-version: 3.12

      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2.8.2

      - 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: "Add SSH key"
        if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS == 'true' }}
        uses: webfactory/ssh-agent@a6f90b1f127823b31d4d4a8d96047790581349bd # v0.9.1
        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: "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