Merge pull request #1060 from RocketPy-Team/develop #22
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 |