Repository navigation
Ci/trustworthy system tests (#403) #58
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/Publish Develop Docs | |
| on: | |
| push: | |
| paths: | |
| - "docs/**" | |
| - "mkdocs.yml" | |
| - "*.md" | |
| - "stacks/**" | |
| - "tools/gen_docs_catalog.py" | |
| - ".github/workflows/deploy_docs_from_develop.yaml" | |
| branches: | |
| - develop | |
| # Module-docs freshness (RFC #379 §9): the catalog is regenerated from the | |
| # live registry on every deploy, so a registry change only reaches the site | |
| # when a deploy runs. Until registry-driven repository_dispatch lands | |
| # ("within a day, exact at releases"), a weekly rebuild plus manual dispatch | |
| # keeps the develop catalog from going stale. | |
| workflow_dispatch: | |
| schedule: | |
| - cron: "17 6 * * 1" # weekly, Mondays 06:17 UTC | |
| permissions: | |
| contents: write | |
| jobs: | |
| deploy: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@v4 | |
| with: | |
| # schedule/workflow_dispatch run on the default branch; this | |
| # workflow always publishes the develop docs. | |
| ref: develop | |
| 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 is fresh even when the committed pages lag. | |
| # 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" | |
| - name: Build Docs Website | |
| run: | | |
| VERSION=$(grep -m1 '^VERSION=' .env | cut -d= -f2- | tr -d '"') | |
| mike deploy --push --title "${VERSION} (unstable)" develop | |
| # mike re-sorts versions.json on every deploy ("main" sorts above | |
| # "develop"), so pin develop — the higher, unreleased version — back | |
| # to the top of the version selector after each deploy. | |
| - name: Reorder version selector (develop above main) | |
| run: | | |
| 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 |