Repository navigation
Open
Labels
Description
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:,kTSKPublicKeyAlgorithmsandTSKSupportedAlgorithm. - They call the report's
app-vendor-idthe IDFV. Since 3.0.1 it has been a random UUID generated per install. - They don't mention visionOS, Mac Catalyst, or the
API_UNAVAILABLEannotations 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.yamlstill listskTSKAdditionalTrustAnchors, 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) anddocs/images/linking3_dynamic.png. The README and getting-started guide load that image by its absolute Pages URL. .github/workflows/release.ymlruns when a release is published, and only attachesTrustKit-static.zip.
Proposal
- Fix the jazzy inputs. Remove
kTSKAdditionalTrustAnchorsfrom.jazzy.yaml, and update the platform list indocs/documentation-readme.md. Optionally, addTrustKitVersionto a category so it doesn't land in "Other Constants". - Add a
docsjob torelease.yml:- Install a pinned jazzy version.
- Run
jazzyfrom the repo root. - Build the Pages artifact from
docs/plus the generateddocs/documentation. - Deploy it with
actions/upload-pages-artifactandactions/deploy-pages. This needspages: writeandid-token: write, and thegithub-pagesenvironment. - Skip prereleases (
if: ${{ !github.event.release.prerelease }}), so a beta doesn't replace the stable docs. - Add a
workflow_dispatchtrigger, so docs can be deployed for an existing release. - Guard the
xcframeworkjob withif: github.event_name == 'release'. Otherwise a manual run would trygh release uploadagainst a branch ref.
- 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.
- Delete
docs/documentationfrom 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.pngand/TrustKit/. - The generated docs don't mention
setLoggerBlock:,kTSKPublicKeyAlgorithms,TSKSupportedAlgorithmor the IDFV. docs/documentationis 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
jazzywithout deploying, to catch broken doc comments? It adds a Ruby install to every run. - jazzy is configured for Objective-C only (
objc: trueplus the umbrella header), soTrustKit/Swiftisn'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 docbuildplusdocc 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, andcustom_categorieswould need a DocC catalog to replace it.
Activity