build.yaml

run-name: build ${{ inputs.repository }}:${{ inputs.reference }}
on:
  workflow_dispatch:
    inputs:
      reference:
        description: 'Commit reference from CPython repository'
        required: true
        default: '3.14'
      repository:
        description: 'Repository to checkout'
        required: false
        default: 'python/cpython'
      publish:
        description: 'Publish to GitHub Pages'
        required: false
        default: false
      python_version:
        description: 'Python version used to generate docs'
        required: false
        default: '3'
  workflow_call:
    inputs:
      reference:
        description: 'Commit reference from CPython repository'
        default: '3.14'
        type: string
      repository:
        description: 'Repository to checkout'
        default: 'python/cpython'
        type: string
      publish:
        description: 'Publish to GitHub Pages'
        default: 'false'
        type: string
      python_version:
        description: 'Python version used to generate docs'
        default: '3'
        type: string
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  prepare:
    runs-on: ubuntu-latest
    outputs:
      dist_version: ${{ steps.get-version.outputs.dist_version }}
      major_minor: ${{ steps.get-version.outputs.major_minor }}
    steps:
      - uses: actions/setup-python@master
        with:
          python-version: ${{ inputs.python_version }}
      - uses: actions/checkout@master
        with:
          repository: ${{ inputs.repository }}
          ref: ${{ inputs.reference }}
      - id: get-version
        run: |
          echo "dist_version=$(python tools/extensions/patchlevel.py --short)" >> $GITHUB_OUTPUT
          echo "major_minor=$(python -c 'from tools.extensions.patchlevel import get_version_info; print(get_version_info()[0])')" >> $GITHUB_OUTPUT
        working-directory: ./Doc
  build-html:
    needs: prepare
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-python@master
        with:
          python-version: ${{ inputs.python_version }}
      - uses: actions/checkout@master
        with:
          repository: ${{ inputs.repository }}
          ref: ${{ inputs.reference }}
      - run: make venv
        working-directory: ./Doc
      - run: make dist-html
        working-directory: ./Doc
      - uses: actions/upload-artifact@master
        if: always()
        with:
          name: python-${{ needs.prepare.outputs.dist_version }}-docs-html.zip
          path: ./Doc/dist/python-${{ needs.prepare.outputs.dist_version }}*-docs-html.zip
          if-no-files-found: ignore
      - uses: actions/upload-artifact@master
        if: always()
        with:
          name: python-${{ needs.prepare.outputs.dist_version }}-docs-html.tar.bz2
          path: ./Doc/dist/python-${{ needs.prepare.outputs.dist_version }}*-docs-html.tar.bz2
          if-no-files-found: ignore
  build-text:
    needs: prepare
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-python@master
        with:
          python-version: ${{ inputs.python_version }}
      - uses: actions/checkout@master
        with:
          repository: ${{ inputs.repository }}
          ref: ${{ inputs.reference }}
      - run: make venv
        working-directory: ./Doc
      - run: make dist-text
        working-directory: ./Doc
      - uses: actions/upload-artifact@master
        if: always()
        with:
          name: python-${{ needs.prepare.outputs.dist_version }}-docs-text.zip
          path: ./Doc/dist/python-${{ needs.prepare.outputs.dist_version }}*-docs-text.zip
          if-no-files-found: ignore
      - uses: actions/upload-artifact@master
        if: always()
        with:
          name: python-${{ needs.prepare.outputs.dist_version }}-docs-text.tar.bz2
          path: ./Doc/dist/python-${{ needs.prepare.outputs.dist_version }}*-docs-text.tar.bz2
          if-no-files-found: ignore
  build-texinfo:
    needs: prepare
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-python@master
        with:
          python-version: ${{ inputs.python_version }}
      - uses: actions/checkout@master
        with:
          repository: ${{ inputs.repository }}
          ref: ${{ inputs.reference }}
      - run: make venv
        working-directory: ./Doc
      - run: sudo apt-get update && sudo apt-get install -y texinfo
      - run: make dist-texinfo
        working-directory: ./Doc
      - uses: actions/upload-artifact@master
        if: always()
        with:
          name: python-${{ needs.prepare.outputs.dist_version }}-docs-texinfo.zip
          path: ./Doc/dist/python-${{ needs.prepare.outputs.dist_version }}*-docs-texinfo.zip
          if-no-files-found: ignore
      - uses: actions/upload-artifact@master
        if: always()
        with:
          name: python-${{ needs.prepare.outputs.dist_version }}-docs-texinfo.tar.bz2
          path: ./Doc/dist/python-${{ needs.prepare.outputs.dist_version }}*-docs-texinfo.tar.bz2
          if-no-files-found: ignore
  build-epub:
    needs: prepare
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-python@master
        with:
          python-version: ${{ inputs.python_version }}
      - uses: actions/checkout@master
        with:
          repository: ${{ inputs.repository }}
          ref: ${{ inputs.reference }}
      - run: make venv
        working-directory: ./Doc
      - run: make dist-epub
        working-directory: ./Doc
      - uses: actions/upload-artifact@master
        if: always()
        with:
          name: python-${{ needs.prepare.outputs.dist_version }}-docs.epub
          path: ./Doc/dist/python-${{ needs.prepare.outputs.dist_version }}*-docs.epub
          if-no-files-found: ignore
  build-pdf:
    needs: prepare
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-python@master
        with:
          python-version: ${{ inputs.python_version }}
      - uses: actions/checkout@master
        with:
          repository: ${{ inputs.repository }}
          ref: ${{ inputs.reference }}
      - run: make venv
        working-directory: ./Doc
      - run: sudo apt-get update && sudo apt-get install -y latexmk texlive-xetex fonts-freefont-otf xindy librsvg2-bin
      - run: make dist-pdf
        working-directory: ./Doc
      - uses: actions/upload-artifact@master
        if: always()
        with:
          name: python-${{ needs.prepare.outputs.dist_version }}-pdf-logs.zip
          path: |
            ./Doc/build/latex/*.log
            ./Doc/build/latex/*.tex
      - uses: actions/upload-artifact@master
        if: always()
        with:
          name: python-${{ needs.prepare.outputs.dist_version }}-docs-pdf-a4.zip
          path: ./Doc/dist/python-${{ needs.prepare.outputs.dist_version }}*-docs-pdf-a4.zip
          if-no-files-found: ignore
      - uses: actions/upload-artifact@master
        if: always()
        with:
          name: python-${{ needs.prepare.outputs.dist_version }}-docs-pdf-a4.tar.bz2
          path: ./Doc/dist/python-${{ needs.prepare.outputs.dist_version }}*-docs-pdf-a4.tar.bz2
          if-no-files-found: ignore
  publish:
    needs: [build-html, build-text, build-texinfo, build-epub, build-pdf]
    if: ${{ !cancelled() && inputs.publish == 'true' }}
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Configure Pages
        uses: actions/configure-pages@v5

      - name: Checkout existing gh-pages content
        id: checkout-pages
        uses: actions/checkout@v5
        with:
          ref: gh-pages
          path: _site
        continue-on-error: true

      - name: Prepare site directory
        run: |
          mkdir -p _site/${{ needs.prepare.outputs.major_minor }}
          # Remove git metadata; safe even if checkout above did not succeed
          rm -rf _site/.git

      - name: Download all artifacts
        # Collect all build artifacts then merge into the publish directory
        uses: actions/download-artifact@v4
        with:
          path: artifacts/

      - name: Copy new archives into site directory
        run: |
          # Copy generated archives (zip, tar.bz2, epub) into _site/<major_minor>/,
          # excluding PDF build logs which are for debugging only.
          find artifacts/ -type f \( -name "*.zip" -o -name "*.tar.bz2" -o -name "*.epub" \) \
            ! -name "python-*-pdf-logs.zip" \
            -exec cp {} _site/${{ needs.prepare.outputs.major_minor }}/ \;

      - name: Generate per-version directory listing
        run: |
          python - <<'PY'
          import re
          from datetime import datetime, timezone
          from html import escape
          from pathlib import Path
          from urllib.parse import quote

          root = Path("_site")
          version_pattern = re.compile(r"^\d+\.\d+$")
          for version_dir in sorted(
              p for p in root.iterdir() if p.is_dir() and version_pattern.match(p.name)
          ):
              files = sorted(
                  p for p in version_dir.iterdir() if p.is_file() and p.name != "index.html"
              )
              rows = []
              for file_path in files:
                  stat = file_path.stat()
                  timestamp = datetime.fromtimestamp(stat.st_mtime, timezone.utc).strftime(
                      "%Y-%m-%d %H:%M:%S UTC"
                  )
                  rows.append(
                      f'<tr><td><a href="{quote(file_path.name)}">{escape(file_path.name)}</a></td><td>{timestamp}</td><td>{stat.st_size}</td></tr>'
                  )

              relative_path = f"/{version_dir.relative_to(root).as_posix()}/"
              html = [
                  "<!doctype html>",
                  '<html lang="en">',
                  '<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Directory listing</title></head>',
                  "<body>",
                  f"<h1>Path: {escape(relative_path)}</h1>",
                  "<table>",
                  '<thead><tr><th scope="col">Filename</th><th scope="col">Timestamp (UTC)</th><th scope="col">Size (bytes)</th></tr></thead>',
                  "<tbody>",
                  *rows,
                  "</tbody>",
                  "</table>",
                  "</body>",
                  "</html>",
              ]
              (version_dir / "index.html").write_text("\n".join(html) + "\n", encoding="utf-8")
          PY

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: _site

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4