docs.yml

name: Docs

on:
  push:
    branches: ["main", "dev"]
  workflow_dispatch:
    inputs:
      ref:
        description: "Optional branch, tag, or SHA to build, such as refs/tags/vX.Y.Z. Runs on main deploy it"
        required: false
        type: string

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build-docs:
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.version.outputs.version }}
    # A newer push to the same branch supersedes a build that is still running. Builds of
    # different refs never cancel each other, so a dev push cannot cancel a main or tag build
    concurrency:
      group: docs-${{ inputs.ref || github.ref }}
      cancel-in-progress: true

    steps:
      - name: Checkout
        uses: actions/checkout@v6
        with:
          # Only override the ref when one is supplied by workflow_dispatch; leaving it
          # empty lets actions/checkout resolve the event.
          ref: ${{ inputs.ref }}
          fetch-depth: 0
          fetch-tags: true

      - name: Fetch tags for setuptools_scm
        run: |
          git fetch --force --tags
          git describe --tags --long --always

      - name: Setup Python
        uses: actions/setup-python@v6
        with:
          # Sphinx 9.1 requires Python 3.12; pytest.yml tests the package on 3.9 to 3.12
          python-version: "3.12"

      - name: Install system dependencies for the PDF build
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            latexmk \
            texlive-luatex \
            texlive-latex-extra \
            texlive-fonts-recommended \
            texlive-pictures \
            fonts-freefont-otf

      - name: Install Python dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -e .[docs]

      - name: Record docs version
        id: version
        run: echo "version=$(python -c "from importlib.metadata import version; print(version('pynetdesign'))")" >> "$GITHUB_OUTPUT"

      - name: Verify release version
        if: >-
          startsWith(github.ref, 'refs/tags/v') ||
          startsWith(inputs.ref, 'refs/tags/v') ||
          startsWith(inputs.ref, 'v')
        shell: bash
        env:
          RELEASE_REF: ${{ inputs.ref || github.ref }}
        run: |
          tag="${RELEASE_REF##*/}"
          expected="${tag#v}"
          actual="$(python -c "from importlib.metadata import version; print(version('pynetdesign').split('+', 1)[0])")"
          if [[ "$actual" != "$expected" ]]; then
            echo "Expected release version $expected from tag $tag, got $actual"
            git describe --tags --long --always
            exit 1
          fi

      - name: Build HTML and PDF docs
        env:
          MPLBACKEND: Agg
        # Invoked through bash so the build does not depend on the executable bit
        run: bash build-docs.sh --pdf

      - name: Upload PDF artifact
        uses: actions/upload-artifact@v7
        with:
          name: pynetdesign-docs-pdf
          path: docs/build/latex/pynetdesign.pdf

      - name: Setup Pages
        uses: actions/configure-pages@v6

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v5
        with:
          path: docs/build/html

  deploy-pages:
    # Only runs on main deploy. GitHub Pages ignores a deployment made from a tag when main
    # has already deployed the same commit (actions/deploy-pages#383), so push-tag.yml
    # starts a run on main to publish a release
    if: github.ref == 'refs/heads/main'
    needs: build-docs
    runs-on: ubuntu-latest
    # Deployments run one at a time, and one that has started always completes
    concurrency:
      group: pages
      cancel-in-progress: false
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

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

      - name: Check the deployed version
        shell: bash
        env:
          PAGE_URL: ${{ steps.deployment.outputs.page_url }}
          EXPECTED: ${{ needs.build-docs.outputs.version }}
        run: |
          # Pages can report success and keep serving the previous upload, so read the version
          # back from the live site. A new query string on each request bypasses the CDN cache
          url="${PAGE_URL%/}/_static/documentation_options.js"
          for attempt in $(seq 1 10); do
            live="$(curl -fsS "$url?check=$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT-$attempt" || true)"
            if [[ "$live" == *"VERSION: '$EXPECTED'"* ]]; then
              echo "The live docs show version $EXPECTED"
              exit 0
            fi
            sleep 30
          done
          echo "::error::The live docs do not show version $EXPECTED. See 'Deploying the docs manually' in RELEASE.md"
          exit 1