.github/workflows/docs.yml

# Builds and tests the docs, then deploys them to GitHub Pages.
#
# Flow: sanity tests -> build -> deploy -> live-site tests. Single
# version, served at the site root (psutil.io). Nothing is committed:
# the built site is uploaded as an artifact and served directly (no
# gh-pages branch, no separate repo).
#
# Repo setup: Settings -> Pages -> Source = "GitHub Actions", and set
# the custom domain to psutil.io.
#
# Prior art if we ever add versioning. Preferred path is the Salt
# model: keep this artifact method and single repo, but fan the build
# out over master + the last few supported release tags (master -> /,
# each tag -> /vX.Y/) and rebuild that set every run. No separate repo,
# no committed HTML, EOL versions drop off. Root stays master so the
# blog keeps publishing; the /vX.Y/ dirs are frozen API snapshots. A
# JS flyout reads a generated versions.json.
#   Salt (this model, in production):
#     https://github.com/saltstack/builddocs/blob/main/.github/workflows/gh-pages-builddocs.yml
#   NumPy (heavier: separate repo, one committed dir per release, by
#   hand) - only for a permanent archive of every past release:
#     https://github.com/numpy/numpy.org/blob/main/.github/workflows/gh-pages.yml
#     https://github.com/numpy/doc

on:
  push:
    branches: [master]
    paths: &docs_paths
      - "docs/**"
      - ".github/workflows/docs.yml"
      - "pyproject.toml"
  pull_request:
    paths: *docs_paths
  workflow_dispatch:

name: docs

concurrency:
  group: docs-deploy
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0 # full history for sphinx-last-updated-by-git

      - uses: actions/setup-python@v7
        with:
          python-version: 3.x

      - name: Install dependencies
        run: |
          make install-pydeps-docs
          make install-pydeps-lint
          make install-pydeps-test
          pip install .                   # codeautolink imports psutil

      - name: Lint rst
        run: make lint-rst

      - name: Doc sanity tests
        run: make -C docs test

      - name: Refresh adoption stats
        # Change is not committed to GIT, but ends up on the live site.
        continue-on-error: true
        run: python3 scripts/internal/refresh_adoption_stats.py

      - name: Build HTML
        run: make -C docs html

      - name: Add deploy marker
        run: echo "${{ github.sha }}" > docs/_build/html/build-sha.txt

      - uses: actions/upload-pages-artifact@v5
        with:
          path: docs/_build/html

  deploy:
    needs: build
    if: github.event_name != 'pull_request'
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v5

  test-online:
    needs: deploy
    if: github.event_name != 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-python@v7
        with:
          python-version: 3.x
      - name: Install dependencies
        run: |
          make install-pydeps-test
          make install-pydeps-docs

      - name: Wait for the live site to serve this commit
        # deploy-pages reports "live" before the CDN edge catches up,
        # so poll build-sha.txt (cache-busted) until it matches.
        run: |
          for i in $(seq 1 60); do
            live=$(curl -fsS "https://psutil.io/build-sha.txt?cb=$i" || true)
            if [ "$live" = "${{ github.sha }}" ]; then
              echo "live site is serving ${{ github.sha }}"
              exit 0
            fi
            echo "waiting for CDN propagation ($i)..."
            sleep 5
          done
          echo "timed out waiting for the deploy to go live"
          exit 1

      - name: Live-site tests
        run: make -C docs test-online-doc