AirStack/.github/workflows/deploy_docs_from_release.yaml at main · castacks/AirStack · 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
name: Build/Publish Latest Release Docs

on:
  release:
    types: [published]

# Serialize gh-pages pushes: concurrent docs deploys race on the branch
# push (observed: develop deploy rejected with 'fetch first' when the main
# deploy pushed at the same time).
concurrency:
  group: docs-deploy-gh-pages
  cancel-in-progress: false
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v4
        with:
          python-version: 3.10.6
      - name: Install Dependencies
        run: |
          pip install mkdocs-material mkdocs-same-dir mkdocs-redirects pyyaml
          pip install pillow cairosvg mike
      # RFC #379 §9: module docs ride the docs deploy. Shallow-clone the
      # registry index and each REGISTERED module repo at its registered_ref
      # into the gitignored modules/ dir, then regenerate docs/modules/ so
      # the published catalog matches the registry at release time.
      # FAILURE ISOLATION: nothing in this step may fail the deploy — an
      # unreachable registry or module repo degrades to the committed pages /
      # a stub note on the module's page.
      - name: Fetch registry index and registered module repos
        run: |
          rm -rf .modules-index modules
          git clone --depth 1 https://github.com/castacks/airstack-modules-index .modules-index \
            || echo "skipped: registry index unreachable (committed catalog pages will be served)"
          if [ -d .modules-index/modules ]; then
            mkdir -p modules
            python3 tools/gen_docs_catalog.py --index .modules-index --list-refs |
            while IFS=$'\t' read -r name repo ref; do
              ( git init -q "modules/$name" \
                && git -C "modules/$name" remote add origin "$repo" \
                && git -C "modules/$name" fetch -q --depth 1 origin "$ref" \
                && git -C "modules/$name" checkout -q FETCH_HEAD ) \
                || { rm -rf "modules/$name"; echo "skipped: module $name ($repo @ $ref) unreachable — its page keeps the stub note"; }
            done
            python3 tools/gen_docs_catalog.py --index .modules-index --modules-dir modules \
              || echo "skipped: catalog regeneration failed (committed pages will be served)"
          fi
      - name: Setup Docs Deploy
        run: |
          git config --global user.name "Docs Deploy"
          git config --global user.email "docs.deploy@example.co.uk"
      # Docs versions use MAJOR.MINOR slugs (e.g. tag 0.21.0 → /0.21/) so a
      # later hotfix can republish the same slug in place without breaking
      # URLs; the selector entry's title carries the full patch version.
      - name: Build Docs Website
        env:
          TAG: ${{ github.event.release.tag_name }}
        run: |
          SLUG=$(echo "${TAG}" | cut -d. -f1-2)
          echo "Deploying release docs: slug ${SLUG}, title ${TAG}"
          mike deploy --push --update-aliases --title "${TAG}" "${SLUG}" main
          # Root URL redirects to the PINNED slug (not the moving alias): URLs
          # people land on and copy stay valid across future releases. /main/
          # remains as a moving alias for deep links.
          mike set-default "${SLUG}" --push
      # mike re-sorts versions.json on every deploy, so pin develop — the
      # higher, unreleased version — back to the top of the version selector
      # after each deploy. Guarded: the script may be absent on release tags
      # cut before it existed.
      - name: Reorder version selector (develop first)
        run: |
          if [ ! -f .github/workflows/scripts/docs_reorder_versions.py ]; then
            echo "skipped: docs_reorder_versions.py not on this tag"
            exit 0
          fi
          git worktree add ../ghp-reorder gh-pages
          python3 .github/workflows/scripts/docs_reorder_versions.py ../ghp-reorder/versions.json
          if ! git -C ../ghp-reorder diff --quiet -- versions.json; then
            git -C ../ghp-reorder commit -m "Reorder version selector: develop above main" versions.json
            git push origin gh-pages
          fi
          git worktree remove ../ghp-reorder