Minor/fixes #127
Workflow file for this run
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: Build and publish Sphinx 🪬 documentation | |
| on: | |
| push: | |
| branches: | |
| - main | |
| - develop | |
| pull_request: | |
| types: [opened, reopened, ready_for_review] | |
| branches: [main, develop] | |
| paths: | |
| - "src/weac/**" | |
| - "docs/sphinx/**" | |
| - "pyproject.toml" | |
| - "README.md" | |
| - ".github/workflows/docs.yml" | |
| workflow_dispatch: | |
| permissions: | |
| contents: write | |
| jobs: | |
| build: | |
| name: Build and publish Sphinx 🪬 documentation | |
| runs-on: ubuntu-latest | |
| environment: docs-deploy | |
| steps: | |
| - name: Check out the repository | |
| uses: actions/checkout@v6 | |
| - name: Set up uv | |
| uses: astral-sh/setup-uv@v7 | |
| with: | |
| version: "latest" | |
| - name: Install dependencies | |
| run: | | |
| uv sync --extra docs | |
| uv pip install IPython | |
| - name: Build documentation | |
| run: | | |
| # Clean any previous build artifacts | |
| uv run make -C docs/sphinx clean | |
| # Generate API docs | |
| uv run sphinx-apidoc -o docs/sphinx/ src/weac --force --separate | |
| # Build HTML docs (do not fail on warnings) | |
| uv run make -C docs/sphinx html SPHINXOPTS="--keep-going -n" | |
| # Ensure .nojekyll file exists for GitHub Pages | |
| touch docs/sphinx/_build/html/.nojekyll | |
| - name: Deploy documentation | |
| if: github.event_name == 'push' && github.ref == 'refs/heads/main' | |
| run: | | |
| set -euo pipefail | |
| git config --local user.email "action@github.com" | |
| git config --local user.name "GitHub Action" | |
| # Build verification - ensure required files exist | |
| if [ ! -f docs/sphinx/_build/html/index.html ]; then | |
| echo "Build output missing (docs/sphinx/_build/html/index.html not found). Aborting deploy." | |
| exit 1 | |
| fi | |
| echo "Build verification passed - index.html found" | |
| # Prepare a clean worktree for the documentation branch | |
| git worktree remove -f docs-deploy || true | |
| git worktree prune | |
| # Ensure we know about the remote branch if it exists | |
| git fetch origin documentation || true | |
| if git show-ref --verify --quiet refs/remotes/origin/documentation; then | |
| # Attach worktree to the remote branch tip and create/point local branch 'documentation' | |
| git worktree add --force -B documentation docs-deploy origin/documentation | |
| else | |
| # Create a new local 'documentation' branch starting from current HEAD (content will be replaced) | |
| git worktree add --force -b documentation docs-deploy HEAD | |
| fi | |
| # Clean the documentation branch but preserve .gitignore if it exists | |
| pushd docs-deploy | |
| # Preserve .gitignore if it exists | |
| if [ -f .gitignore ]; then | |
| cp .gitignore /tmp/preserve-gitignore | |
| fi | |
| git rm -rf . || true | |
| git clean -fxd | |
| # Restore .gitignore if it existed | |
| if [ -f /tmp/preserve-gitignore ]; then | |
| cp /tmp/preserve-gitignore .gitignore | |
| rm /tmp/preserve-gitignore | |
| fi | |
| popd | |
| # Create proper directory structure for GitHub Pages | |
| mkdir -p docs-deploy/docs | |
| # Copy built HTML to the docs directory (for GitHub Pages) | |
| cp -r docs/sphinx/_build/html/* docs-deploy/docs/ | |
| # Ensure .nojekyll file exists in the docs directory for GitHub Pages | |
| touch docs-deploy/docs/.nojekyll | |
| pushd docs-deploy | |
| git add -A | |
| if git diff --cached --quiet; then | |
| echo "No changes to publish" | |
| exit 0 | |
| else | |
| git commit -m "Update documentation" -m "🪬 Generated with Sphinx from main branch" | |
| git fetch origin documentation --quiet || true | |
| git push --force-with-lease origin HEAD:documentation | |
| fi | |
| popd |