From 4980c1f1e0770c6a366600805dd1093b570022ba Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 14 Jul 2026 06:21:35 +0000 Subject: [PATCH 1/2] CI: publish DocC catalog to GitHub Pages on merge to master Implements #33. Publish the rendered ReliaBLE DocC catalog to a stable, browsable GitHub Pages URL instead of a per-PR zip artifact. - Build DocC with static-hosting flags (--transform-for-static-hosting, --hosting-base-path ReliaBLE, --disable-indexing). The build still runs on every PR with --warnings-as-errors, preserving the DocC gate from #32. - Upload the Pages artifact and deploy via actions/upload-pages-artifact + actions/deploy-pages (modern GitHub Pages deploy mechanics), gated to pushes on master only. - Remove the per-PR ReliaBLE-docs.zip artifact upload. - Scope permissions least-privilege at the workflow level; the deploy job elevates pages/id-token. - Link the hosted docs (and a local build note) from README.md, replacing the TODO placeholder. PR preview strategy: PRs validate the catalog via the CI gate; local preview is via `swift package generate-documentation`. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01U78GaqPWrWJCwYGqo1ZdNu --- .github/workflows/ci.yml | 46 ++++++++++++++++++++++++++++++---------- README.md | 7 +++++- 2 files changed, 41 insertions(+), 12 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 50234c7..7cc556e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -9,6 +9,10 @@ concurrency: group: ci-${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true +# Least-privilege default; the deploy-docs job elevates what it needs. +permissions: + contents: read + jobs: docc: name: DocC catalog @@ -29,18 +33,38 @@ jobs: - name: Verify Swift version run: swift --version + # Builds the static-hosting site AND acts as the DocC validation gate on + # every PR via --warnings-as-errors. The extra static-hosting flags don't + # affect validation; they just shape the output for GitHub Pages. - name: Build DocC catalog run: | - swift package --allow-writing-to-directory ./docc-output \ - generate-documentation --target ReliaBLE --warnings-as-errors \ - --output-path ./docc-output - - - name: Archive DocC output - run: ditto -c -k --sequesterRsrc --keepParent docc-output ReliaBLE-docs.zip + swift package --allow-writing-to-directory ./docs \ + generate-documentation --target ReliaBLE \ + --disable-indexing \ + --transform-for-static-hosting \ + --hosting-base-path ReliaBLE \ + --output-path ./docs \ + --warnings-as-errors - - name: Upload DocC archive - uses: actions/upload-artifact@v4 + # Only publish from master; PRs validate but do not deploy. + - name: Upload Pages artifact + if: github.ref == 'refs/heads/master' + uses: actions/upload-pages-artifact@v3 with: - name: ReliaBLE-docs - path: ReliaBLE-docs.zip - if-no-files-found: error \ No newline at end of file + path: ./docs + + deploy-docs: + name: Deploy documentation + if: github.ref == 'refs/heads/master' + needs: docc + runs-on: ubuntu-latest + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/README.md b/README.md index 02e3cf1..8369e4c 100644 --- a/README.md +++ b/README.md @@ -12,4 +12,9 @@ Modern library for handling BLE connections, with a focus on reliability. ## Documentation -- Getting Started [TODO DOC LINK: Add link once doc site is up] +Full API documentation is published from `master` to GitHub Pages: + +- [ReliaBLE Documentation](https://five3apps.github.io/ReliaBLE/documentation/reliable/) +- [Getting Started](https://five3apps.github.io/ReliaBLE/documentation/reliable/gettingstarted) + +To build the documentation locally, run `swift package generate-documentation`. From d4a23a49a5d10aa483075195bdba866cb8d03e72 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 15 Jul 2026 01:58:24 +0000 Subject: [PATCH 2/2] Trim README Documentation section to just the doc links Address PR review: drop the "published from master" intro and the local build note; keep only the hosted documentation links for now. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01U78GaqPWrWJCwYGqo1ZdNu --- README.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/README.md b/README.md index 8369e4c..c5c796c 100644 --- a/README.md +++ b/README.md @@ -12,9 +12,5 @@ Modern library for handling BLE connections, with a focus on reliability. ## Documentation -Full API documentation is published from `master` to GitHub Pages: - - [ReliaBLE Documentation](https://five3apps.github.io/ReliaBLE/documentation/reliable/) - [Getting Started](https://five3apps.github.io/ReliaBLE/documentation/reliable/gettingstarted) - -To build the documentation locally, run `swift package generate-documentation`.