Build Documentation #92
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
| # Builds Sphinx documentation after Python Build completes successfully. | |
| # Uploads documentation artifact for review or deployment. | |
| name: Build Documentation | |
| on: | |
| workflow_run: | |
| workflows: ["Python CI"] | |
| types: | |
| - completed | |
| push: | |
| branches: | |
| - 'dev' | |
| tags: | |
| - '**' | |
| paths: | |
| - '.github/workflows/build-docs.yml' | |
| - 'docs/**' | |
| - 'pyproject.toml' | |
| # Cancel a currently running workflow from the same PR, branch or tag when a new workflow is triggered: | |
| concurrency: | |
| group: ${{ github.workflow }}-${{ github.event.workflow_run.head_sha || github.sha }} | |
| cancel-in-progress: true | |
| jobs: | |
| build_docs: | |
| name: Documentation | |
| runs-on: ubuntu-latest | |
| # For workflow_run: only run if tests passed and it's dev or a version tag | |
| # For push: always run | |
| if: | | |
| github.event_name == 'push' || ( | |
| github.event.workflow_run.conclusion == 'success' && | |
| ( | |
| github.event.workflow_run.head_branch == 'dev' || | |
| startsWith(github.event.workflow_run.head_branch, 'v') | |
| ) | |
| ) | |
| permissions: | |
| packages: write | |
| env: | |
| UV_LOCKED: true | |
| UV_COMPILE_BYTECODE: true | |
| UV_NO_EDITABLE: true | |
| UV_NO_PROGRESS: true | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v6 | |
| # https://github.com/actions/setup-python | |
| - name: Install uv and set the python version | |
| id: setup-uv | |
| uses: astral-sh/setup-uv@v7 | |
| with: | |
| # https://docs.astral.sh/uv/guides/integration/github/#using-uv-in-github-actions | |
| # It is considered best practice to pin to a specific uv version | |
| version: "0.9.26" | |
| # https://github.com/astral-sh/setup-uv?tab=readme-ov-file#enable-caching | |
| enable-cache: true | |
| cache-dependency-glob: uv.lock | |
| - name: Build documentation | |
| # Options: | |
| # -T Display the full traceback when an unhandled exception occurs | |
| # -E Don't use a saved environment (the structure caching all cross-references), but rebuild it completely. | |
| # -b Select the builder | |
| # -d Select a different cache directory | |
| # -D Override a configuration value set in the conf.py file | |
| # -W Turn warnings into errors. This means that the build stops at the first warning and sphinx-build exits with exit status 1 | |
| # --keep-going With -W option, keep going processing when getting warnings to the end of build, and sphinx-build exits with exit status 1. | |
| run: > | |
| uv run | |
| --group doc | |
| python -m sphinx | |
| -T -E | |
| -b html | |
| -d _build/doctrees | |
| -D language=en | |
| -W --keep-going | |
| . _build/html | |
| working-directory: docs | |
| # Save the generated documentation as an artifact in Github | |
| - name: Upload documentation | |
| uses: actions/upload-artifact@v7 | |
| with: | |
| name: python-doc-package | |
| path: docs/_build/ |