name: documentation
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
workflow_dispatch:
permissions:
contents: write
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Configure Pages
uses: actions/configure-pages@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.11'
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install ".[dev]"
pip install -r docs/requirements.txt
- name: Generate repository table of contents
run: |
python scripts/generate_repo_toc.py \
--output docs/repository-map.md \
--repo "${{ github.repository }}" \
--ref "${{ github.sha }}" \
--tree-ref "${{ github.sha }}"
- name: Build documentation (versioned)
run: sphinx-multiversion docs docs/_build/html
- name: Write root index.html that redirects to default version
run: |
set -euo pipefail
build="docs/_build/html"
# Pick default target: prefer 'latest', then 'main', else first dir
if [ -d "$build/latest" ]; then target="latest"
elif [ -d "$build/main" ]; then target="main"
else target="$(ls -1 "$build" | head -n1)"
fi
echo "Default docs version: $target"
cat > "$build/index.html" <<'HTML'
Redirecting…
Redirecting to documentation: __TARGET__/
HTML
sed -i "s|__TARGET__|$target|g" "$build/index.html"
- name: Upload site artifact
uses: actions/upload-pages-artifact@v3
with:
path: docs/_build/html
deploy:
runs-on: ubuntu-latest
needs: build
if: github.event_name != 'pull_request'
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
permissions:
pages: write
id-token: write
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4