From b2f34e0aafa69b640b0bdb4bf4e9fe68f4a76665 Mon Sep 17 00:00:00 2001 From: Bill Wolf Date: Thu, 25 Jun 2026 16:53:56 -0500 Subject: [PATCH] Add docs workflow to build and deploy on release The Sphinx docs under docs/ were never regenerated automatically; they are a static 2017 snapshot served by GitHub Pages. Add a docs workflow that rebuilds the docs from docstrings (sphinx autodoc) and deploys them to Pages on release publication (mirroring the PyPI publish trigger), so the published docs track each release. Also supports manual dispatch. Adds requirements-docs.txt pinning the doc toolchain (sphinx, sphinx_rtd_theme, sphinx-copybutton). NOTE: requires the repo's Pages source to be set to "GitHub Actions" (Settings -> Pages) instead of "Deploy from a branch", since this uses actions/deploy-pages. Co-Authored-By: Claude Opus 4.8 --- .github/workflows/docs.yml | 54 ++++++++++++++++++++++++++++++++++++++ .gitignore | 4 +++ requirements-docs.txt | 3 +++ 3 files changed, 61 insertions(+) create mode 100644 .github/workflows/docs.yml create mode 100644 requirements-docs.txt diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..08d3333 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,54 @@ +# Build the Sphinx documentation and publish it to GitHub Pages whenever a +# release is published (the same trigger used to publish to PyPI), so the docs +# track each released version rather than every push. + +name: docs + +on: + release: + types: [published] + # Allow a manual rebuild from the Actions tab without cutting a release. + workflow_dispatch: + +# Permissions required by actions/deploy-pages. +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment; don't cancel an in-progress one. +concurrency: + group: pages + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.x" + - name: Install dependencies + run: | + python -m pip install --upgrade pip + # autodoc imports mesa_reader, so the package and its runtime deps + # must be installed alongside the documentation tooling. + pip install . + pip install -r requirements-docs.txt + - name: Build HTML docs + run: sphinx-build -b html docs_source _site + - uses: actions/upload-pages-artifact@v3 + with: + path: _site + + deploy: + needs: build + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index 0c6347a..14cf09c 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,7 @@ make.bat *.egg-info .buildinfo .vscode +.venv +.pytest_cache +_site +docs_build diff --git a/requirements-docs.txt b/requirements-docs.txt new file mode 100644 index 0000000..d014eb7 --- /dev/null +++ b/requirements-docs.txt @@ -0,0 +1,3 @@ +sphinx +sphinx_rtd_theme +sphinx-copybutton