script and data to build the combined collection of docs#72
Open
heckj wants to merge 30 commits intoswiftlang:mainfrom
Open
script and data to build the combined collection of docs#72heckj wants to merge 30 commits intoswiftlang:mainfrom
heckj wants to merge 30 commits intoswiftlang:mainfrom
Conversation
Member
Author
|
The swift-book repo, in particular, needs some specific prep work for it's catalog prior to running |
heckj
added a commit
to swiftlang/swift-book
that referenced
this pull request
Apr 3, 2026
This lets us run this setup script with an external repository's (swiftlang/docs) build script to do the expected prep work for the DocC catalog in order to combine it with other DocC catalogs for a combined archive of multiple doc sets together. work needed to support swiftlang/docs#72, ultimately to support swiftlang/docs#24
…e built alongside the output
Add Apache 2.0 license headers to all _empty.swift files and build-docs.sh. Add .licenseignore to exclude files that cannot have license headers (Package.swift, .gitkeep, .html, README). Configure license_header_check_project_name in CI workflow.
Replace build-docs.sh with build_docs.py, removing the --branch CLI option, fallback_branch field, and latest-release auto-detection. Each git source now has an explicit "ref" field in sources.json, making builds fully deterministic. The combined archive is named <version>.doccarchive (e.g. main.doccarchive) and individual archives are intermediates cleaned up after merge.
Runs the build_docs.py script on PRs and pushes to main using the swift:6.2-noble container, caches .workspace/ between runs, and uploads the merged .doccarchive as a CI artifact.
github-actions bot
added a commit
to ekassos/swift-book-archive
that referenced
this pull request
Apr 4, 2026
extracts the grammar generation step into it's own script (#454) This lets us run this setup script with an external repository's (swiftlang/docs) build script to do the expected prep work for the DocC catalog in order to combine it with other DocC catalogs for a combined archive of multiple doc sets together. work needed to support swiftlang/docs#72, ultimately to support swiftlang/docs#24 Upstream commit: swiftlang/swift-book@2306b38
The swift:6.2-noble image does not include python3, causing the build step to fail with exit code 127.
The swift:6.2-noble release image fails to build swift-testing docs. The swift-testing CI itself uses nightly-main images, so align with that.
The shared swiftlang/github-workflows default to jammy (Ubuntu 22.04). nightly-main-noble crashed in libdispatch; 6.2-noble failed on swift-testing. Try the release toolchain on jammy.
swift-testing requires Swift tools version 6.3.0, so 6.2.x images can't build it. Use nightly-main on jammy (Ubuntu 22.04) which is the platform swift-testing CI actually runs on.
Use --output-dir to write to a known path under GITHUB_WORKSPACE, and add a debug ls step to verify output before upload.
The swift-book preflight (bin/generate-grammar) fails if its output file already exists from a previous cached run. Adding git clean -fdx ensures untracked files from prior builds are removed.
DocC archives contain colons in filenames (e.g. when(configuration:).json) which upload-artifact rejects. Package as a tarball instead. Also add explanatory comment on the git clean step.
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.
Summary
Related Issue
Closes: #24
Additional Notes
DOCC_JSON_PRETTYPRINT=YESto make the output a bit more deterministic (diffs are easier if we need to debug or merge in changes in source control)--experimental-enable-custom-templates w/ header & footer from common/
--enable-mentioned-in
--enable-experimental-external-link-support (completely arbitrary- can drop)
Script CLI:
Most of the time in this script is cloning and (for the docs that need it) resolving the packages before building the docs (SwiftPM & swiftly). Once it's all cloned and resolved, doing a rebuild of the content is pretty quick:
time scripts/build-docs.sh:Once built, see the result locally:
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.