Publish the manual to Gitea Pages

As KPN publishes its docs: a workflow copies docs/manual/index.html and its pictures onto the gitea-pages branch, served at https://pages.tourolle.paris/dtourolle/darkroom/. No site generator, since the page is already rendered and the Traceability workflow keeps it in step with the README. The pictures come from LFS as build-and-test.yml fetches the models, and the job refuses to publish a pointer in place of a picture.
2026-10-08 22:23:10 -04:00
parent f813014e80
commit 90d0985db8
1 changed files with 77 additions and 0 deletions
@@ -0,0 +1,77 @@
+name: Manual pages
+
+# Publishes the manual to Gitea Pages, the way KPN publishes its docs: the
+# site is whatever the `gitea-pages` branch holds, served at
+# https://pages.tourolle.paris/dtourolle/darkroom/.
+#
+# No site generator. docs/manual/index.html is already the rendered page —
+# `cargo run -p traceability -- manual` writes it from README.md, and the
+# Traceability workflow fails a push whose page disagrees with the README —
+# so this job only copies the page and its pictures onto the branch.
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - 'docs/manual/**'
+      - '.gitea/workflows/manual-pages.yml'
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: linux/amd64
+    name: Publish the manual
+    container:
+      image: catthehacker/ubuntu:act-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # The pictures are in LFS, so a plain checkout would publish pointers.
+      # Fetched as build-and-test.yml fetches the models, and for the reason
+      # written there: checkout's Authorization header and the per-object JWT
+      # Gitea hands git-lfs collide into a 400, so the header goes and the
+      # token travels as a credential instead.
+      - name: Fetch the manual's pictures
+        env:
+          TOKEN: ${{ secrets.GITEA_TOKEN || github.token }}
+        run: |
+          set -e
+          git lfs install --local
+          git config --local --get-regexp '^http\..*extraheader$' \
+            | cut -d' ' -f1 | sort -u \
+            | while read -r key; do git config --local --unset-all "$key"; done || true
+          git config --local lfs.url \
+            "https://x-access-token:${TOKEN}@gitea.tourolle.paris/dtourolle/DarkRoom.git/info/lfs"
+          git lfs pull --include="docs/manual/media/**"
+
+      # A pointer is ~130 bytes of text; a picture is not. Publishing a page of
+      # broken images is worse than publishing nothing, so check before pushing.
+      - name: Refuse pointers
+        run: |
+          set -e
+          bad=$(find docs/manual/media -type f -size -1k -exec grep -l '^version https://git-lfs' {} + || true)
+          if [ -n "$bad" ]; then
+            echo "LFS pointers where pictures should be:"; echo "$bad"; exit 1
+          fi
+
+      # One commit, force-pushed: the branch is a build output, and its history
+      # is in master's.
+      - name: Push to gitea-pages
+        env:
+          TOKEN: ${{ secrets.GITEA_TOKEN || github.token }}
+        run: |
+          set -e
+          site=$(mktemp -d)
+          cp docs/manual/index.html "$site/"
+          cp -r docs/manual/media "$site/"
+          cd "$site"
+          git init -q -b gitea-pages
+          git config user.name "Gitea Actions"
+          git config user.email "actions@gitea.tourolle.paris"
+          git add -A
+          git commit -q -m "manual: deploy from ${GITHUB_SHA}"
+          git push -f \
+            "https://x-access-token:${TOKEN}@gitea.tourolle.paris/dtourolle/DarkRoom.git" \
+            gitea-pages