docs.yml

name: Docs

on:
  push:
    branches: [main]
    paths:
      - "docs/**"
      - "src/**"            # doxygen-generated XML feeds breathe
      - "Doxyfile"
      - ".github/workflows/docs.yml"
  pull_request:
    branches: [main]
    paths:
      - "docs/**"
      - "Doxyfile"
      - ".github/workflows/docs.yml"
  workflow_dispatch:

# Allow only one concurrent deployment.
concurrency:
  group: pages
  cancel-in-progress: true

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    name: Build multiproject docs
    runs-on: ubuntu-latest
    steps:
      - name: Checkout (with submodules)
        uses: actions/checkout@v4
        with:
          submodules: recursive
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"
          cache: pip
          cache-dependency-path: docs/requirements.txt

      - name: Install Doxygen
        run: |
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends doxygen graphviz

      - name: Install Python deps
        run: pip install -r docs/requirements.txt

      - name: Build site
        run: |
          cd docs
          # `all-versions` builds every version in the Makefile's
          # *_VERSIONS lists into /<project>/<version>/ subdirs
          # (latest at /<project>/), each from a temp git worktree of
          # the submodule at that tag/branch.  DOCS_DEPLOY_BASE must
          # be set or the version targets fall back to their
          # localhost preview default.
          # Serial build (SPHINXOPTS="-q", no `-j auto`): sphinx-tippy
          # mutates app.env.tippy_data from html-page-context, and in
          # parallel mode those worker-process mutations never reach
          # the build-finished hook that writes _static/tippy/*.js.
          # -W (warnings-as-errors) is intentionally not enabled yet.
          SPHINXOPTS="-q" DOCS_DEPLOY_BASE=https://microrobotica.org make all-versions

      - name: Upload Pages artifact
        if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/_build/html

  deploy:
    name: Deploy to GitHub Pages
    needs: build
    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v4