Repository navigation
hotfix(docs): MAJOR.MINOR docs slugs; retire the duplicate 'main' doc… #77
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 Main Docs | |
| on: | |
| push: | |
| paths: | |
| - "docs/**" | |
| - "mkdocs.yml" | |
| - "*.md" | |
| - "stacks/**" | |
| - "tools/gen_docs_catalog.py" | |
| - ".github/workflows/deploy_docs_from_main.yaml" | |
| branches: | |
| - main | |
| 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 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" | |
| # Stable docs live under a MAJOR.MINOR slug (e.g. /0.20/) — there is | |
| # no separate "main" docs version (it duplicated the release entry in | |
| # the version selector). A hotfix merged to main republishes the same | |
| # slug in place and retitles the selector entry to the new patch | |
| # version, so URLs never break within a minor line. | |
| - name: Build Docs Website | |
| run: | | |
| VERSION=$(grep -m1 '^VERSION=' .env | cut -d= -f2- | tr -d '"') | |
| SLUG=$(echo "${VERSION}" | cut -d. -f1-2) | |
| echo "Deploying main's docs: slug ${SLUG}, title ${VERSION}" | |
| mike deploy --push --update-aliases --title "${VERSION}" "${SLUG}" latest | |
| mike set-default latest --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. | |
| - name: Reorder version selector (develop first) | |
| 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 |