Build and Deploy Sphinx Documentation #189
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 Deploy Sphinx Documentation | |
| on: | |
| push: | |
| workflow_dispatch: | |
| inputs: | |
| deploy: | |
| description: 'Deploy to GitHub Pages after building' | |
| type: boolean | |
| default: true | |
| openadstack_ref: | |
| description: 'openadstack branch to check out for its submodule (blank = the branch tracked in .gitmodules)' | |
| type: string | |
| default: '' | |
| openadsim_ref: | |
| description: 'openadsim branch to check out for its submodule (blank = the branch tracked in .gitmodules)' | |
| type: string | |
| default: '' | |
| permissions: | |
| contents: read | |
| packages: read | |
| pages: write | |
| id-token: write | |
| concurrency: | |
| group: "pages" | |
| cancel-in-progress: false | |
| jobs: | |
| build: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| with: | |
| lfs: true | |
| - name: Set up Python | |
| uses: actions/setup-python@v5 | |
| with: | |
| python-version: '3.11' | |
| cache: 'pip' | |
| cache-dependency-path: 'docs/requirements.txt' | |
| - name: Install dependencies | |
| run: | | |
| python -m pip install --upgrade pip | |
| pip install -r docs/requirements.txt | |
| - name: Update submodules to latest state | |
| env: | |
| OPENADSTACK_REF: ${{ inputs.openadstack_ref }} | |
| OPENADSIM_REF: ${{ inputs.openadsim_ref }} | |
| run: | | |
| # The runner cannot use the SSH/internal remotes from .gitmodules; use HTTPS repositories instead | |
| git config submodule.docs/openadstack/openadstack.url "https://github.com/openads-project/openadstack.git" | |
| git config submodule.docs/openadsim/openadsim.url "https://github.com/openads-project/openadsim.git" | |
| # When dispatched for a specific submodule branch (e.g. by a repo's trigger workflow), track that | |
| # branch for the submodule so the docs are built from the branch that triggered this run. | |
| if [ -n "${OPENADSTACK_REF}" ]; then | |
| git config submodule.docs/openadstack/openadstack.branch "${OPENADSTACK_REF}" | |
| fi | |
| if [ -n "${OPENADSIM_REF}" ]; then | |
| git config submodule.docs/openadsim/openadsim.branch "${OPENADSIM_REF}" | |
| fi | |
| git submodule update --init --recursive | |
| # `git submodule update` alone checks out the superproject-pinned commit. For any | |
| # submodule with an overridden branch, advance it to the latest commit on that branch. | |
| if [ -n "${OPENADSTACK_REF}" ]; then | |
| git submodule update --init --recursive --remote docs/openadstack/openadstack | |
| fi | |
| if [ -n "${OPENADSIM_REF}" ]; then | |
| git submodule update --init --recursive --remote docs/openadsim/openadsim | |
| fi | |
| - name: Inject calculated disk sizes into docs | |
| run: | | |
| bash -c "export COMPOSE_PROFILES=demo-basic && docs/assets/inject_disk_sizes.sh docs/openadstack/openadstack/demo/docker-compose.yml docs/start/start.md DISK_SIZE_OPENADSTACK" | |
| bash -c "export COMPOSE_PROFILES=demo-extended && docs/assets/inject_disk_sizes.sh docs/openadstack/openadstack/demo/docker-compose.yml docs/start/start.md DISK_SIZE_PERCEPTION" | |
| bash -c "docs/assets/inject_disk_sizes.sh docs/openadsim/openadsim/docker-compose.yml docs/start/start.md DISK_SIZE_OPENADSIM" | |
| - name: Build Sphinx documentation | |
| run: | | |
| set -eo pipefail | |
| cd docs | |
| # Build the docs, echoing the output while also capturing it, then fail if Sphinx emitted a warning. | |
| sphinx-build -b html . _build/html 2>&1 | tee build.log | |
| if grep -q "WARNING:" build.log; then | |
| echo "::error::Sphinx build produced warnings (see the log above)." | |
| exit 1 | |
| fi | |
| - name: Upload artifact | |
| uses: actions/upload-pages-artifact@v3 | |
| with: | |
| path: 'docs/_build/html' | |
| deploy: | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| runs-on: ubuntu-latest | |
| needs: build | |
| # Deploy on direct pushes to main, or when a workflow_dispatch (e.g. from the openadstack repo) | |
| # explicitly requests it. Build-only runs (other branches) skip this job. | |
| if: >- | |
| (github.event_name == 'push' && github.ref == 'refs/heads/main') || | |
| (github.event_name == 'workflow_dispatch' && inputs.deploy) | |
| steps: | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@v4 |