publish-docs.yml

# Publish the Ruff 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

jobs:
  mkdocs:
    runs-on: ubuntu-latest
    env:
      MKDOCS_INSIDERS_SSH_KEY_EXISTS: ${{ secrets.MKDOCS_INSIDERS_SSH_KEY != '' }}
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ inputs.ref }}
          persist-credentials: true

      - 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, 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 "version=$version" >> "$GITHUB_ENV"
          echo "display_name=$display_name" >> "$GITHUB_ENV"

      - name: "Set branch name"
        run: |
          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 Rust toolchain"
        run: rustup show

      - uses: Swatinem/rust-cache@v2

      - 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: "Copy README File"
        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

      - name: "Build docs"
        if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS != 'true' }}
        run: mkdocs build --strict -f mkdocs.public.yml

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

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

      - name: "Commit docs"
        working-directory: astral-docs
        run: |
          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: |
          # 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
          # 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: |
          # 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}"