feat(workflow): Gitea-Wiki als generierter Spiegel von docs/ (#192)

Konverter .gitea/scripts/wiki_mirror.py, Push-Skript wiki-push.sh, Job wiki-mirror in release.yml, Dispatch-Workflow wiki-mirror.yml und --check-Schritt in ci.yml. Version 9.0.0-beta.13.

Files changed:
- .gitea/scripts/wiki-push.sh
- .gitea/scripts/wiki_mirror.py
- .gitea/workflows/ci.yml
- .gitea/workflows/release.yml
- .gitea/workflows/wiki-mirror.yml
- CHANGES.md
- README.md
- VERSION
- docs/dev/development.md
- tools/chemenu/tests/test_wiki_mirror.py

Co-Authored-By: Claude Code <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2

.gitea/workflows/ci.yml

@@ -194,6 +194,14 @@ jobs:
           tools/wikitool instructions verify
           tools/wikitool lint --fail-on-error
 
+      - name: Wiki mirror converts the docs
+        # The Gitea wiki mirrors docs/ at every release (release.yml, job wiki-mirror). A link the
+        # converter cannot resolve, or two pages that would share a wiki name, is cheaper to hear
+        # about here than when the release is cut. Writes nothing.
+        run: |
+          set -eu
+          python3 .gitea/scripts/wiki_mirror.py --check --source . --version "$(tr -d '[:space:]' < VERSION)"
+
       - name: Version gate
         # A stack change with no version bump cannot be released, because the
         # release would carry a change nobody named. Scoped to what

.gitea/workflows/release.yml

@@ -17,6 +17,13 @@
 # instance issues - not a 1Password secret. Nothing here reaches outside the
 # instance, so the Zero-Trust secret path that the container-build workflows
 # use has nothing to carry.
+#
+# `wiki-mirror` is the second job: once `release` has published a release, it
+# mirrors that tree's docs into the Gitea wiki (.gitea/scripts/wiki_mirror.py
+# converts, wiki-push.sh pushes; wiki-mirror.yml does the same by hand for any
+# tag). It is a separate job so that a failing mirror leaves the release and its
+# tag standing: the release is the product, the wiki a view of it. It does not
+# run for a `-beta.N` candidate, for which `release` sets `skip`.
 
 name: Release
 
@@ -38,6 +45,10 @@ jobs:
       image: debian:trixie-slim
     permissions:
       contents: write
+    outputs:
+      skip: ${{ steps.version.outputs.skip }}
+      version: ${{ steps.version.outputs.version }}
+      tag: ${{ steps.version.outputs.tag }}
     env:
       WIKITOOL_SESSION_ID: release-${{ github.run_id }}
       WIKI_TRACE_DIR: /tmp/wikitool-trace
@@ -233,3 +244,43 @@ jobs:
           done
 
           echo "Done: ${PUBLIC_BASE_URL}/${GITHUB_REPOSITORY}/releases/tag/${TAG}"
+
+  wiki-mirror:
+    # Runs only after `release` succeeded and created a release (a candidate
+    # sets skip=true). `release` never depends on this job.
+    needs: release
+    if: needs.release.outputs.skip != 'true'
+    runs-on: linux-docker
+    container:
+      image: debian:trixie-slim
+    permissions:
+      contents: write
+    env:
+      VERSION: ${{ needs.release.outputs.version }}
+      TAG: ${{ needs.release.outputs.tag }}
+      PUBLIC_BASE_URL: https://gitea.nehmer.net
+
+    steps:
+      - name: System dependencies
+        run: |
+          set -eu
+          apt-get update -qq
+          apt-get install -y --no-install-recommends python3 git nodejs ca-certificates curl jq
+          rm -rf /var/lib/apt/lists/*
+
+      - uses: actions/checkout@v7
+
+      - name: Mirror the docs into the wiki
+        env:
+          WIKI_TOKEN: ${{ gitea.token }}
+        run: |
+          set -eu
+          python3 .gitea/scripts/wiki_mirror.py --source . --out /tmp/wiki-out \
+            --version "$VERSION" --repo-url "${PUBLIC_BASE_URL}/${GITHUB_REPOSITORY}"
+          .gitea/scripts/wiki-push.sh /tmp/wiki-out "$VERSION"
+
+      - name: Say which half failed
+        if: failure()
+        run: |
+          echo "Release ${TAG} is published; only the wiki mirror failed."
+          echo "The release and its tag stand. Dispatch wiki-mirror.yml with tag ${TAG} to retry the mirror."

.gitea/workflows/wiki-mirror.yml

@@ -0,0 +1,78 @@
+# Mirror the docs of one release tag into the Gitea wiki, by hand.
+#
+# The same two scripts as the `wiki-mirror` job in release.yml, started on demand:
+# to fill the wiki for the first time and look at it before the next release,
+# and to catch up a mirror that failed after its release was already published.
+# The wiki is a mirror and never a source - every run replaces its whole content,
+# and nothing but CI writes to it.
+#
+# The converter and the push script come from the commit this workflow runs on
+# (main); the docs come from the tag, checked out beside it. That way an old tag,
+# whose tree predates the converter, can still be mirrored.
+#
+# Input `tag` defaults to the latest release, read from the release API.
+
+name: Wiki mirror
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to mirror (default: the latest release)'
+        required: false
+        default: ''
+
+jobs:
+  mirror:
+    runs-on: linux-docker
+    container:
+      image: debian:trixie-slim
+    permissions:
+      contents: write
+    env:
+      PUBLIC_BASE_URL: https://gitea.nehmer.net
+
+    steps:
+      - name: System dependencies
+        run: |
+          set -eu
+          apt-get update -qq
+          apt-get install -y --no-install-recommends python3 git nodejs ca-certificates curl jq
+          rm -rf /var/lib/apt/lists/*
+
+      - uses: actions/checkout@v7
+
+      - name: Resolve the tag
+        id: tag
+        env:
+          API: ${{ github.server_url }}/api/v1/repos/${{ github.repository }}
+          TOKEN: ${{ gitea.token }}
+          INPUT_TAG: ${{ github.event.inputs.tag }}
+        run: |
+          set -eu
+          tag="$INPUT_TAG"
+          if [ -z "$tag" ]; then
+            tag="$(curl -sS -f -H "Authorization: token ${TOKEN}" "${API}/releases/latest" | jq -r '.tag_name')"
+          fi
+          case "$tag" in
+            v[0-9]*) ;;
+            *) echo "Tag '${tag}' is not a release tag (vX.Y.Z)."; exit 1 ;;
+          esac
+          echo "Mirroring ${tag}."
+          echo "tag=${tag}" >> "$GITHUB_OUTPUT"
+          echo "version=${tag#v}" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ steps.tag.outputs.tag }}
+          path: tag-tree
+
+      - name: Mirror the docs into the wiki
+        env:
+          VERSION: ${{ steps.tag.outputs.version }}
+          WIKI_TOKEN: ${{ gitea.token }}
+        run: |
+          set -eu
+          python3 .gitea/scripts/wiki_mirror.py --source tag-tree --out /tmp/wiki-out \
+            --version "$VERSION" --repo-url "${PUBLIC_BASE_URL}/${GITHUB_REPOSITORY}"
+          .gitea/scripts/wiki-push.sh /tmp/wiki-out "$VERSION"