CI: Publish DocC catalog to hosted documentation site

[itsniper]

Goal

Publish the rendered ReliaBLE DocC catalog to a hosted, browsable URL (instead of — or in addition to — downloading a zip artifact from PR checks). Reviewers and library consumers should be able to open documentation in a browser without checking out a branch or unzipping a .doccarchive.

Context

• Parent: NFR 11: Continuous Integration (GitHub Actions) #21 (NFR 11 — CI)
• Prerequisite: CI: Build DocC catalog on every PR #22 (DocC build gate in CI) — implemented in CI: Build DocC catalog on every PR (#22) #32. The current workflow validates DocC on every PR and uploads ReliaBLE-docs.zip as a PR artifact for manual preview.
• The audit report (docs/investigations/swift6-concurrency-audit-2026-05-13.md, Preventive Measures) called out DocC-in-CI as a drift guardrail; hosted docs were explicitly deferred as a follow-up.
• README.md still has a placeholder: Getting Started [TODO DOC LINK: Add link once doc site is up].
• DocC catalog: Sources/ReliaBLE/Documentation.docc/. swift-docc-plugin is already a package dependency.

Problem with artifacts-only

PR artifacts work for reviewers who know to download and unzip, but they are:

• Ephemeral (retention-limited)
• Not linkable from README.md, release notes, or issue comments
• Awkward on mobile / for casual contributors
• Separate from the "public documentation surface" consumers expect from an OSS library

Deliverable (decision needed)

Choose and implement a hosting strategy. At minimum:

1. Publish on merge to master (not necessarily on every PR — see options below).
2. Update README.md with a stable documentation URL once live.
3. Decide PR preview strategy — keep artifact upload for PRs, add per-PR preview deploys, or rely on local swift package generate-documentation only.

Hosting options (typical in OSS GitHub projects)

Option A — GitHub Pages via Actions (most common for Swift packages)

The pattern Apple documents for swift-docc-plugin: build with static-hosting flags, deploy HTML to GitHub Pages.

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

• URL shape: https://five3apps.github.io/ReliaBLE/ (project site; base path = repo name)
• Deploy mechanics (pick one):
  • Modern: actions/upload-pages-artifact + actions/deploy-pages (requires enabling GitHub Pages → "GitHub Actions" source in repo settings)
  • Classic: peaceiris/actions-gh-pages pushing to gh-pages branch
  • Docs folder: commit rendered output to /docs on master (simpler, but bloats main-branch history unless using a bot)
• Pros: Free, zero external accounts, standard for Swift OSS (e.g. many swiftlang/* and community packages)
• Cons: Public only (unless GitHub Enterprise Pages); base-path config must match repo name

References:

• swift-docc-plugin: Publishing to GitHub Pages
• GitHub Pages: configuring a publishing source

Option B — GitHub Pages preview deploys for PRs (optional add-on)

Use a workflow that deploys to a preview URL per PR (e.g. actions/deploy-pages with a preview environment, or Netlify/Cloudflare Pages deploy previews).

• Pros: Reviewers click a link in the PR checks comment — no zip download
• Cons: More workflow complexity; preview URL lifecycle / cleanup; may need a bot comment on each PR
• Typical split: publish stable docs from master (Option A) + keep artifact or preview for PRs

Option C — Swift Package Index (zero-maintenance discovery)

Swift Package Index auto-builds and hosts documentation for many public Swift packages once indexed.

• Pros: No hosting workflow to maintain; great discoverability in the Swift ecosystem
• Cons: Not under our control (build schedule, availability badge, URL); does not replace a first-party link in README.md for all consumers
• Typical use: complementary to Option A, not a substitute

Option D — Third-party static host (Netlify / Cloudflare Pages / Vercel)

Upload the --transform-for-static-hosting output as a static site.

• Pros: Fast CDN, easy preview branches, custom domains
• Cons: Extra service account/secrets; less conventional for small Swift libraries; another thing to pay attention to
• Typical use: teams already on that stack, or needing private docs

Option E — Drop PR artifacts once hosted docs exist

Once Option A (and optionally B) is live, remove the ReliaBLE-docs.zip artifact upload from .github/workflows/ci.yml to simplify CI — or keep it as a fallback for offline preview.

Suggested default (for decision review)

For a library of this size, the usual OSS path is:

1. Option A — GitHub Pages published on every push to master via actions/deploy-pages
2. Keep CI: Build DocC catalog on every PR #22's validation gate on every PR (--warnings-as-errors) — unchanged
3. Remove or demote PR artifacts once the Pages URL is linked from README.md
4. Optionally register with Swift Package Index for ecosystem visibility (no workflow required)

Acceptance criteria

• A stable, public documentation URL exists and is linked from README.md
• Docs are rebuilt and published automatically when master changes (after DocC gate passes)
• Published site renders the ReliaBLE DocC catalog correctly (navigation, symbol pages, articles)
• Decision documented: PR preview strategy (artifact vs preview deploy vs local-only)

References

• Parent: NFR 11: Continuous Integration (GitHub Actions) #21 (NFR 11 — CI)
• Prerequisite: CI: Build DocC catalog on every PR #22 / PR CI: Build DocC catalog on every PR (#22) #32 (DocC CI gate + artifact)
• Investigation report: docs/investigations/swift6-concurrency-audit-2026-05-13.md (Preventive Measures)
• README.md documentation placeholder