cd.yml

name: Deploy API Docs

# Build the Sphinx API docs inside the dev image (same slim-Python + uv
# environment everything else uses — no conda) and publish to gh-pages.
# autodoc imports shapepipe, so it needs the full runtime; the dev image's
# `doc` extra provides sphinx + myst-parser + the theme on top of that.
on:
  push:
    branches:
      - master
      - main
  workflow_dispatch:

jobs:
  api:
    name: Deploy API Documentation
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
        with:
          driver-opts: network=host

      - name: Build dev image
        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
        with:
          context: .
          target: dev
          load: true
          tags: shapepipe-dev:docs
          cache-from: type=gha
          cache-to: type=gha,mode=max

      # Generate API stubs and build the HTML inside the image. docs/ is
      # bind-mounted so sphinx-apidoc's generated rst and the _build output
      # land back on the runner for the deploy step.
      - name: Build API documentation
        run: |
          docker run --rm -v "${GITHUB_WORKSPACE}/docs:/app/docs" shapepipe-dev:docs bash -c "
            sphinx-apidoc -t docs/_templates -feTMo docs/source shapepipe shapepipe/modules/*_runner.py &&
            sphinx-build -E docs/source docs/_build
          "

      - name: Deploy API documentation
        uses: peaceiris/actions-gh-pages@84c30a85c19949d7eee79c4ff27748b70285e453 # v4.1.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: docs/_build