docs.yml

name: Documentation

on:
  # Only PRs targeting master (base branch = master) and pushes to master.
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
    branches: [master]
    paths:
      - "docs/**"
      - "rocketpy/**" # docstrings feed the autodoc API reference
      - "pyproject.toml"
      - "requirements*"
      - ".readthedocs.yaml"
      - ".github/workflows/docs.yml"
  push:
    branches: [master]
    paths:
      - "docs/**"
      - "rocketpy/**"
      - "pyproject.toml"
      - "requirements*"
      - ".readthedocs.yaml"
      - ".github/workflows/docs.yml"

# Least privilege: this workflow only needs to read the repository.
permissions:
  contents: read

defaults:
  run:
    shell: bash

jobs:
  build-docs:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.12"] # match the Read the Docs build environment
    env:
      MPLBACKEND: Agg
      # Render jupyter-execute cells as static code blocks instead of running
      # them. This keeps the check fast and deterministic: no simulations and,
      # crucially, no live network calls to external weather/data servers (which
      # make the full build slow and flaky). Read the Docs still executes the
      # cells to render live outputs; this job only validates the docs structure
      # (reStructuredText, cross-references, toctrees, autodoc API reference).
      DOCS_SKIP_EXECUTE: "1"
    steps:
      - uses: actions/checkout@v4

      - name: Install pandoc (required by nbsphinx)
        run: sudo apt-get update && sudo apt-get install -y pandoc

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          cache: "pip"
          cache-dependency-path: |
            docs/requirements.txt
            requirements.txt

      - name: Install dependencies (mirrors .readthedocs.yaml)
        run: |
          python -m pip install --upgrade pip
          pip install -r docs/requirements.txt
          pip install -r requirements.txt
          pip install .[all]

      - name: Cache Sphinx doctrees
        uses: actions/cache@v4
        with:
          path: docs/_build/doctrees
          key: sphinx-doctrees-${{ github.ref }}-${{ hashFiles('docs/**', 'rocketpy/**') }}
          restore-keys: |
            sphinx-doctrees-${{ github.ref }}-
            sphinx-doctrees-

      - name: Build docs (warnings-as-errors)
        working-directory: docs
        run: |
          sphinx-build -b html -W --keep-going \
            -d _build/doctrees \
            -w _build/sphinx-warnings.txt \
            . _build/html

      - name: Surface Sphinx warnings as annotations
        if: always()
        run: |
          if [ -s docs/_build/sphinx-warnings.txt ]; then
            echo "::group::Sphinx warnings"
            cat docs/_build/sphinx-warnings.txt
            echo "::endgroup::"
            while IFS= read -r line; do
              echo "::warning::${line}"
            done < docs/_build/sphinx-warnings.txt
          else
            echo "No Sphinx warnings 🎉"
          fi

      - name: Upload built HTML
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: docs-html
          path: docs/_build/html
          if-no-files-found: error