Evaluate BNGL parameter expressions instead of dropping them (#673) #252
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: 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 |