Add Swift-DocC documentation hosting on GitHub Pages #541
Conversation
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
- Generates symbol graphs and builds documentation using docc - --preview: Local preview server with configurable port - --port: Specify preview server port (default: 8000) - --clean: Force rebuild of symbol graphs - --minimum-access-level: Control symbol visibility (public/internal/private) - --target: Specify module to document - Automatic port conflict detection with user prompt - Reuses existing build artifacts for fast preview iterations - GitHub Pages deployment via gh-pages branch
- Create build-documentation.sh for building and previewing documentation - Refactor update-gh-pages-documentation.sh to focus only on GitHub Pages deployment - Add --source-service and --source-service-base-url options to enable source code links - update-gh-pages-documentation.sh now calls build-documentation.sh internally - Support --no-build option to deploy pre-built documentation
- Default --source-service to 'github' - Default --source-service-base-url to OpenSwiftUI main branch - Source links are now enabled by default - Can still be overridden for forks or custom branches
- Detect module name from data/documentation/*.json files - Use lowercase module name for preview URL (e.g., openswiftuicore) - Fixes 404 errors when accessing documentation preview
- Use --target OpenSwiftUI when generating symbol graphs - Only include OpenSwiftUI and OpenSwiftUICore symbol graphs - Exclude re-exported system modules (Foundation, CoreFoundation, etc.) - Documentation now shows OpenSwiftUI as main entry point
- Force push to gh-pages by default to avoid accumulating large binary files - Add --no-force flag to preserve history if needed - Prevents repo from growing rapidly with each documentation update - Reference: uxlfoundation/oneAPI-spec#334
- Add Python script to filter symbol graph JSON files - Extract module names from Swift mangled identifiers - Only keep OpenSwiftUI and OpenSwiftUICore symbols - Remove CoreFoundation, CoreGraphics, and other system framework symbols - Reduces symbol count from 10,185 to 4,298 (OpenSwiftUI + OpenSwiftUICore only)
- Automatically run swift package clean when no symbol graphs exist - Ensures symbol graphs are always generated on first run - Prevents 'Symbol graph generation failed' error when build is up-to-date - Subsequent runs reuse existing symbol graphs for fast iterations
- Check for TARGET_NAME.symbols.json instead of just the directory - Prevents false positive when only dependency symbol graphs exist - Ensures OpenSwiftUI symbol graphs are always generated
Only copy OpenSwiftUI*.symbols.json files, not OpenSwiftUICore*.symbols.json. Since OpenSwiftUI uses @_exported import OpenSwiftUICore, the OpenSwiftUI symbol graph already contains all re-exported OpenSwiftUICore symbols. This ensures only one documentation module (openswiftui) is generated, with all OpenSwiftUICore symbols appearing under openswiftui instead of a separate openswiftuicore module.
The previous pattern OpenSwiftUI*.symbols.json incorrectly matched OpenSwiftUICore.symbols.json because 'OpenSwiftUICore' starts with 'OpenSwiftUI'. Changed to use two explicit copy commands: 1. OpenSwiftUI.symbols.json (exact match) 2. OpenSwiftUI@*.symbols.json (extension symbol graphs like @AppKit, @swift) This ensures only OpenSwiftUI's own symbol graphs are included, not OpenSwiftUICore's. Since OpenSwiftUI uses @_exported import OpenSwiftUICore, all OpenSwiftUICore symbols are already included in OpenSwiftUI.symbols.json.
…reation - Use 'git add -Af .' to override .gitignore rules that prevent tracking files in the .docs directory - Create orphan branch in main working tree before creating worktree to ensure the branch exists properly - This fixes deployment failures where files were ignored and the gh-pages branch wasn't created
- Add git_push() function to support --echo-without-push for testing - Add --echo-without-push CLI option to echo push commands without executing - Change gh-pages worktree location from .docs/gh-pages to gh-pages/ - Copy documentation files to gh-pages/docs/ subdirectory instead of root - Add gh-pages to .gitignore to exclude worktree from main branch - This fixes the issue where .docs, Example, and .swiftpm folders were incorrectly included in gh-pages branch
- Explain documentation architecture and hosting setup - Provide usage instructions for build-documentation.sh script - Provide usage instructions for update-gh-pages-documentation.sh script - Document why self-hosted was chosen over Swift Package Index - Include troubleshooting guide and advanced usage examples - Explain technical details of symbol filtering and deployment process
- Add TODO for removing default implementations from docs - Add TODO for migrating to GitHub Actions for automated deployment
- Add link to new GitHub Pages documentation as primary source - Mention legacy SwiftPackageIndex version with OpenSwiftUICore limitation - Use concise link labels for better readability
Kyle-Ye
force-pushed
the
feature/docc-github-pages
branch
from
7276332 to
9430cde
Compare
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #541 +/- ##
=======================================
Coverage 24.31% 24.31%
=======================================
Files 506 506
Lines 28979 28979
=======================================
Hits 7047 7047
Misses 21932 21932 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Summary
This PR adds comprehensive Swift-DocC documentation generation and deployment to GitHub Pages, replacing the previous Swift Package Index approach. The documentation is now live at:
https://openswiftuiproject.github.io/OpenSwiftUI/documentation/openswiftui/
Changes
Documentation Scripts
Scripts/build-documentation.sh- Build and preview documentation locallyScripts/update-gh-pages-documentation.sh- Deploy documentation to GitHub Pages--echo-without-pushflag for testing deploymentsgh-pages/docs/subdirectoryKey Features
@_exported import OpenSwiftUICoreto show all APIs under the OpenSwiftUI moduleTechnical Improvements
.gitignorewhen force-adding files in gh-pages branchDocumentation
Added comprehensive
Docs/Documentation.mdexplaining:Motivation
We initially used Swift Package Index for documentation, which worked well but had limitations:
@_exported import(#9101)Self-hosting provides full control over the documentation pipeline and resolves these architectural constraints.
Testing
--hosting-base-path /OpenSwiftUIChecklist
Docs/Documentation.md.gitignoreupdated to excludegh-pages/worktreeFuture Work