docs.yml

name: docs

# Build the Sphinx docs and publish them to GitHub Pages
# (https://lanl.github.io/PyBNF/). This is the interim host while a maintainer
# account is provisioned on Read the Docs; once RTD is live the two can coexist
# or this can be retired. Pages is configured with build_type=workflow (Settings
# -> Pages -> Source: GitHub Actions), so this workflow IS the publish source --
# there is no gh-pages branch.

on:
  push:
    branches: [main]
    # Only rebuild/redeploy the site when something that affects it changes. An
    # unrelated push (another workflow, packaging metadata) should not fire a
    # Pages deploy -- every deploy risks a transient Pages-backend flake, so we
    # don't spend them on no-op runs.
    paths:
      - 'docs/**'
      - 'pybnf/**'
      - 'pyproject.toml'
      - '.github/workflows/docs.yml'
  # Build (but do not deploy) on PRs that touch the docs or the documented code,
  # so a broken build is caught before it reaches main.
  pull_request:
    paths:
      - 'docs/**'
      - 'pybnf/**'
      - 'pyproject.toml'
      - '.github/workflows/docs.yml'
  workflow_dispatch:

# Permissions the deploy-pages action requires: write the Pages deployment and
# mint the OIDC token it authenticates with. Everything else stays read-only.
permissions:
  contents: read
  pages: write
  id-token: write

# Serialize Pages deployments: never let two runs deploy concurrently. Do not
# cancel an in-progress deploy (cancel-in-progress: false) -- a half-finished
# Pages deploy is worse than waiting.
concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      # Reuse the tests' composite action: it installs pybnf + its runtime deps
      # into a uv venv -- exactly the environment autodoc needs to import pybnf
      # on Linux. (It also fetches BNG2.pl, unused here but harmless; the win is
      # one source of truth for the dependency list.)
      - uses: ./.github/actions/setup-pybnf
        with:
          python-version: '3.12'
          # autodoc only imports pybnf; it never simulates. Skip the bngsim
          # install and build under PYBNF_NO_BNGSIM=1 (below) so the docs job
          # stays lean -- and so a docs build keeps proving that pybnf imports
          # cleanly with no backend present.
          bngsim: 'false'
          # Distinct uv cache namespace so this job does not race the tests /
          # lint jobs' content-addressed cache saves on the same push.
          cache-suffix: docs

      - name: Install Sphinx
        run: uv pip install 'sphinx>=7,<9'

      - name: Build HTML docs
        env:
          # autodoc imports pybnf; with bngsim absent the package's bngsim
          # imports are guarded, same as the test suite.
          PYBNF_NO_BNGSIM: '1'
        # -W turns Sphinx warnings into errors so a malformed docstring / RST bug
        # (bad field list, unbalanced inline markup, short title underline, broken
        # ref) fails the build instead of silently degrading the rendered page. The
        # tree was driven warning-clean, so this holds the line. --keep-going
        # collects ALL warnings in one run rather than aborting on the first.
        run: uv run --no-sync sphinx-build -W --keep-going -b html docs docs/_build/html

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

  deploy:
    needs: build
    # Only main publishes; PR builds above are validation-only.
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4