shapepipe/.github/workflows/cd.yml at develop · CosmoStat/shapepipe · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
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.
#
# The published site is versioned. Each ref builds at its own time, in its own
# image, into its own slice of the gh-pages branch:
#   master / main  -> site root           (stable; keeps existing URLs working)
#   develop        -> /latest/
#   tags  v*       -> /<tag>/             (e.g. /v1.1.0/)
# A `switcher.json` at the site root drives the version dropdown. Pull requests
# build the docs and upload them as an artifact, but do not deploy — so a broken
# docs build is caught before merge, and reviewers can preview the rendered HTML.
on:
  push:
    branches:
      - master
      - main
      - develop
    tags:
      - "v*"
  # On PRs, build + upload the docs (no deploy) only when something that affects
  # them changes, so a broken docs build is caught before merge.
  pull_request:
    paths:
      - "docs/**"
      - "src/**"
      - "pyproject.toml"
      - ".github/workflows/cd.yml"
  workflow_dispatch:

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

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

      - name: Resolve version slug
        id: slug
        # Map the pushed ref to a version label (DOCS_VERSION, used by conf.py to
        # highlight the switcher) and a gh-pages destination directory ("." = root).
        run: |
          case "${GITHUB_REF}" in
            refs/tags/*)        slug="${GITHUB_REF#refs/tags/}"; dir="${slug}" ;;
            refs/heads/develop) slug="latest";                  dir="latest"  ;;
            refs/heads/master|refs/heads/main) slug="stable";   dir="."       ;;
            *)                  slug="latest";                  dir="latest"  ;;
          esac
          echo "slug=$slug" >> "$GITHUB_OUTPUT"
          echo "dir=$dir"   >> "$GITHUB_OUTPUT"

      - 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. DOCS_VERSION tells conf.py
      # which version this build represents (for the switcher highlight).
      - name: Build API documentation
        run: |
          docker run --rm -e DOCS_VERSION="${{ steps.slug.outputs.slug }}" \
            -v "${GITHUB_WORKSPACE}/docs:/app/docs" shapepipe-dev:docs bash -c "
              sphinx-apidoc -t docs/_templates -feTMo docs/source src/shapepipe src/shapepipe/modules/*_runner.py &&
              sphinx-build -E docs/source docs/_build
            "

      - name: Upload built HTML as artifact
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: docs-html-${{ steps.slug.outputs.slug }}
          path: docs/_build

      # Stage the gh-pages payload: the build under its version directory, plus a
      # fresh switcher.json at the root so the dropdown stays current whenever any
      # version is published.
      - name: Stage versioned site
        if: github.event_name != 'pull_request'
        run: |
          target="site"
          [ "${{ steps.slug.outputs.dir }}" != "." ] && target="site/${{ steps.slug.outputs.dir }}"
          mkdir -p "$target"
          cp -r docs/_build/. "$target"/
          cp docs/switcher.json site/switcher.json

      # keep_files: true so each deploy only writes its own version directory (and
      # the root switcher.json) and never wipes the other versions on the branch.
      - name: Deploy API documentation
        if: github.event_name != 'pull_request'
        uses: peaceiris/actions-gh-pages@84c30a85c19949d7eee79c4ff27748b70285e453 # v4.1.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: site
          keep_files: true