Skip to content

Generate the API docs in the release workflow instead of committing them #379

Open

Description

@alexanderdibenedetto

Problem

The API docs at https://datatheorem.github.io/TrustKit/documentation are HTML that jazzy generates and that is committed to docs/documentation. They were last regenerated on 2019-08-03 (c06934b, jazzy 0.10.0), so they describe TrustKit 1.6:

  • They still document APIs that 4.0 removes: +setLoggerBlock:, kTSKPublicKeyAlgorithms and TSKSupportedAlgorithm.
  • They call the report's app-vendor-id the IDFV. Since 3.0.1 it has been a random UUID generated per install.
  • They don't mention visionOS, Mac Catalyst, or the API_UNAVAILABLE annotations on the macOS-only symbols.

The README (lines 27 and 84) and docs/getting-started.md (lines 138, 149 and 287) link to these pages. The config is stale too:

  • .jazzy.yaml still lists kTSKAdditionalTrustAnchors, which no longer exists.
  • docs/documentation-readme.md, the docs landing page, lists only iOS, macOS, tvOS and watchOS.

Regenerating by hand is why the docs went stale, and committing generated HTML makes PR diffs noisy.

Current setup

  • GitHub Pages builds in legacy mode from master:/docs.
  • Besides the API docs, Pages serves docs/index.html (a redirect to the repo) and docs/images/linking3_dynamic.png. The README and getting-started guide load that image by its absolute Pages URL.
  • .github/workflows/release.yml runs when a release is published, and only attaches TrustKit-static.zip.

Proposal

  1. Fix the jazzy inputs. Remove kTSKAdditionalTrustAnchors from .jazzy.yaml, and update the platform list in docs/documentation-readme.md. Optionally, add TrustKitVersion to a category so it doesn't land in "Other Constants".
  2. Add a docs job to release.yml:
    • Install a pinned jazzy version.
    • Run jazzy from the repo root.
    • Build the Pages artifact from docs/ plus the generated docs/documentation.
    • Deploy it with actions/upload-pages-artifact and actions/deploy-pages. This needs pages: write and id-token: write, and the github-pages environment.
    • Skip prereleases (if: ${{ !github.event.release.prerelease }}), so a beta doesn't replace the stable docs.
    • Add a workflow_dispatch trigger, so docs can be deployed for an existing release.
    • Guard the xcframework job with if: github.event_name == 'release'. Otherwise a manual run would try gh release upload against a branch ref.
  3. Switch Pages to deploy from GitHub Actions. This is an admin setting: Settings → Pages → Source. Run the workflow manually right after the switch, so the site isn't left without a deployment.
  4. Delete docs/documentation from the repo and add it to .gitignore, so local runs don't get committed.

Acceptance criteria

  • Publishing a non-prerelease release deploys API docs built from that tag's headers.
  • A manual run deploys the docs and skips the XCFramework upload.
  • Existing URLs still resolve, including /TrustKit/documentation/Classes/TrustKit.html, /TrustKit/documentation/Classes/TSKPinningValidator.html, /TrustKit/images/linking3_dynamic.png and /TrustKit/.
  • The generated docs don't mention setLoggerBlock:, kTSKPublicKeyAlgorithms, TSKSupportedAlgorithm or the IDFV.
  • docs/documentation is no longer tracked.

Open questions

  • Should betas deploy docs? With the prerelease guard, Pages keeps the old docs until 4.0.0 ships, unless someone runs the workflow manually.
  • Should PR CI run jazzy without deploying, to catch broken doc comments? It adds a Ruby install to every run.
  • jazzy is configured for Objective-C only (objc: true plus the umbrella header), so TrustKit/Swift isn't documented. That's fine while the Swift code is internal, but it needs a decision when public Swift API lands.

Alternatives considered

  • Regenerate in each release PR into master. This needs no settings change, but it still depends on someone remembering, and it keeps generated HTML in the repo.
  • Have the release job commit the docs to master. This keeps legacy Pages, but CI would need push access to master.
  • Switch to DocC (xcodebuild docbuild plus docc process-archive transform-for-static-hosting). It needs no Ruby dependency, but every docs URL changes, links in the README, the guide and other sites break, and custom_categories would need a DocC catalog to replace it.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions