From 48fcbb5e7e71499d746d7b9e850a0d11c5fece99 Mon Sep 17 00:00:00 2001 From: "Jeffrey C. Ollie" Date: Thu, 27 Aug 2026 21:37:19 -0500 Subject: [PATCH] publish the api documentation from ci zig build docs generates the reference but nothing served it, so reading it meant cloning the repository and running a local web server, which is required rather than optional: the generated page is a wasm viewer that fetches sources.tar, and opening index.html from the filesystem gives an empty page. The job publishes the output to Codeberg Pages, at https://jcollie.codeberg.page/zig-hidapi/ . It runs in this workflow rather than one of its own because `needs` only refers to jobs within a single workflow, and a separate file could not wait on the tests. Waiting on them is the point: a tree that no longer compiles should not replace the published reference. It is also confined to the default branch, since without that any pushed branch would publish its own documentation over the live site. The git-pages action is pinned to the v2.2.0 commit like the others here, because its `v2` names a branch head that moves. Checked locally that zig build docs writes index.html, main.js, main.wasm and sources.tar into zig-out/docs, which is what the publish step is pointed at. Note that sources.tar is around 17 MB, and the action commits it to the pages branch on every push to main. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_011JRTRSt3F4KkHY7ip2MgEk --- .forgejo/workflows/test.yaml | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/.forgejo/workflows/test.yaml b/.forgejo/workflows/test.yaml index 4ec1578..edcd652 100644 --- a/.forgejo/workflows/test.yaml +++ b/.forgejo/workflows/test.yaml @@ -68,3 +68,38 @@ jobs: zig build test -Doptimize=Debug --summary all zig build test -Doptimize=ReleaseSafe --summary all zig build test -Doptimize=ReleaseFast --summary all + + docs: + # Publishes the generated API reference to + # https://jcollie.codeberg.page/zig-hidapi/ . + # + # This lives in the same workflow as the tests because `needs` only refers + # to jobs within one workflow; a separate file could not wait on them. The + # tests have to be green first, so a build that no longer compiles never + # replaces the published documentation. + needs: test + # ...and only from the default branch, or any pushed branch would publish + # over the live site. + if: ${{ forge.ref == 'refs/heads/main' }} + runs-on: codeberg-small + steps: + - name: Check out + uses: https://code.forgejo.org/actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - name: Install Zig + uses: https://codeberg.org/mlugg/setup-zig@d1434d08867e3ee9daa34448df10607b98908d29 # v2.2.1 + + - name: Build the API documentation + run: | + zig version + zig build docs + + # git-pages resolves `v2` to a branch head, which moves; this is the + # v2.2.0 release commit, pinned like the other actions here. It commits + # the directory to the `pages` branch, which is what Codeberg serves. + - name: Publish to Codeberg Pages + uses: https://codeberg.org/git-pages/action@2b24bbb7ff943d3c8fe1df91326adec66daea6dd # v2.2.0 + with: + site: https://${{ forge.repository_owner }}.codeberg.page/zig-hidapi/ + token: ${{ forge.token }} + source: zig-out/docs/ -- knotmirror 0.0.1