feat(swift-docs): Swift Symbol Graph → TypeDoc JSON pipeline#43
Closed
grdsdev wants to merge 9 commits into
Closed
feat(swift-docs): Swift Symbol Graph → TypeDoc JSON pipeline#43grdsdev wants to merge 9 commits into
grdsdev wants to merge 9 commits into
Conversation
…pace, complete fixture and tests
Add module-to-category mapping to transformSymbolGraph so Swift module names (Auth, PostgREST, etc.) map to TypeDoc @category labels required by the Supabase docs pipeline. Extend the CLI to accept an optional categories JSON file as a third argument. Add supabase-swift-categories.json as the default mapping for the supabase-community/supabase-swift SDK. Wire the generate-swift-docs job into aggregate-capabilities.yml: a macOS runner checks out supabase-swift, runs swift-docs, and uploads the TypeDoc JSON as an artifact; the ubuntu deploy job downloads it into site/swift/ before publishing to GitHub Pages. The generated JSON will be served at supabase.github.io/sdk/swift/typedoc.json for consumption by the apps/docs Makefile in supabase/supabase.
…pace, complete fixture and tests Switch extractor to swift package dump-symbol-graph (Swift 6 compatible); output lands in .build/<arch>/symbolgraph/. Skip cross-module extension files and tolerate non-zero exit for test-only targets that can't load on the current platform. Fix two real-world edge cases found during e2e testing against supabase-swift: - functionSignature.returns absent on Void functions → Void intrinsic type - functionSignature.parameters absent on zero-param methods → no parameters field Use umbrella Supabase module name as the TypeDoc project name when present. Fix CI repository name to supabase/supabase-swift.
…ggregate workflow TypeDoc JSON should be hosted on supabase-swift's own GitHub Pages (supabase.github.io/supabase-swift/v2/spec.json), mirroring the JS pattern where each SDK repo publishes its own spec. This keeps aggregate-capabilities.yml focused on the compliance matrix. Add generate-swift-docs.yml as a ready-to-copy workflow template for supabase/supabase-swift. It checks out this sdk repo for the swift-docs tool, generates TypeDoc JSON, and publishes to GitHub Pages.
Collaborator
Author
|
Closing — the swift-docs tool has been moved to supabase/supabase-swift where it belongs alongside the SDK it serves. The CI workflow in that repo now uses the local copy rather than checking out supabase/sdk. See supabase/supabase-swift#1034. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds
scripts/swift-docs/— a standalone TypeScript package that converts Swift SDK symbol graphs into TypeDoc-compatible JSON for the Supabase docs pipeline. Also ships a ready-to-copy CI workflow forsupabase/supabase-swift.Why
The supabase/supabase docs site already has a TypeDoc-based reference pipeline for JavaScript. This wires Swift into the same pipeline so the Swift v2 reference at supabase.com/docs/reference/swift/v2 is generated automatically from source instead of maintained by hand in a YAML spec.
How it works
Key design decisions
swift package dump-symbol-graph(Swift 6 compatible) instead of the oldswift build -Xswiftc -emit-symbol-graph-dirflag which broke in Swift 6supabase-swift-categories.json: Auth→Authentication, PostgREST→Database, Realtime→Realtime, Storage→Storage, Functions→Edge Functions, Supabase→Client. Categories are injected as@categoryTypeDoc blockTags, which the docs pipeline requires for visibilityAuth@Foundation.symbols.jsonetc) — only primary module files are processed@category→ hidden from docs automaticallySupabasemodule when presentChanges
scripts/swift-docs/(new package)src/symbol-graph.tssrc/typedoc-types.tssrc/doc-comment.tssrc/transform.ts@categoryinjectionsrc/extract.tsswift package dump-symbol-graph, reads.build/<arch>/symbolgraph/src/index.tstsx src/index.ts <sdk-root> [output.json] [categories.json]supabase-swift-categories.jsongenerate-swift-docs.yml41 tests across doc-comment parser and transform core.
.github/workflows/aggregate-capabilities.ymlNo changes from main — the Swift docs generation lives in supabase-swift, not here.
Companion PRs
generate-swift-docs.ymlworkflow; publishes tosupabase.github.io/supabase-swift/v2/spec.jsonSUPPORTS_NEW_REFERENCE_PROCESS)Test plan
cd scripts/swift-docs && npm test— 41 tests passnpm run typecheck— cleannpx tsx src/index.ts /path/to/supabase-swift typedoc.json supabase-swift-categories.jsonproduces valid JSON withSupabaseClient(category: Client) andAuthClient(category: Authentication)