I am attempting to document a Swift Package that I plan on making Open Source. I am working on hosting DocC documentation on GitHub. After some work I have finally got it to work with the following command.
swift package --allow-writing-to-directory ./docs generate-documentation --target [PACKAGE-NAME] \
--disable-indexing \
--transform-for-static-hosting \
--hosting-base-path [REPOSITORY-NAME] \
--output-path ./docs
The issue with this command, is that it does not include any of the private symbols. Because I want this documentation for contributors and not for library use, I would like these private symbols to be included in the documentation. To try and fix this, I added -Xswiftc -symbol-graph-minimum-access-level -Xswiftc private
to the command. This is supposed to trigger the Swift compiler to add all private symbols to the symbol graph. However, none of the private symbols are appearing in the documentation.
The full command:
swift package -Xswiftc -symbol-graph-minimum-access-level -Xswiftc private \
--allow-writing-to-directory ./docs generate-documentation --target [PACKAGE-NAME] \
--disable-indexing \
--transform-for-static-hosting \
--hosting-base-path [REPOSITORY-NAME] \
--output-path ./docs
Any help to get the right command would be great!
1 Like
are you trying to compile a symbolgraph (an input artifact to a documentation engine like DocC) or are you trying to compile a static documentation website?
I am trying to compile a static documentation website
Hi @TaylorLineman – Swift-DocC doesn't fully support contributor documentation for frameworks today. I've definitely heard requests for that, but I'm not actually seeing a GitHub Issue for it so if you have a minute to file one and explain your use-case that would be really appreciated.
In the mean time, it is possible to generate the documentation you're looking for by providing DocC with a symbol graph that includes private symbols. Currently xcodebuild
supports this, but not the Swift-DocC Plugin. We're tracking support with [SR-15765] CLI option for choosing level of access to expose when assembling documentation for internal consumption · Issue #11 · apple/swift-docc-plugin · GitHub.
To achieve this with xcodebuild, you can run something like the following:
xcodebuild docbuild -scheme [TargetName] \
-destination generic/platform=macOS \
OTHER_SWIFT_FLAGS='-symbol-graph-minimum-access-level private' \
DOCC_HOSTING_BASE_PATH='[REPOSITORY-NAME]' \
OTHER_DOCC_FLAGS='--disable-indexing'
There's documentation here that explains how to extract the built documentation archive from derived data: Distributing documentation to external developers | Apple Developer Documentation
I also wanted to note that generally I recommend setting the minimum access level to internal
, not private
when building contributor documentation for frameworks. Setting private
may give you more symbols than you're actually looking for.
xcodebuild docbuild -scheme [TargetName] \
-destination generic/platform=macOS \
OTHER_SWIFT_FLAGS='-symbol-graph-minimum-access-level internal' \
DOCC_HOSTING_BASE_PATH='[REPOSITORY-NAME]' \
OTHER_DOCC_FLAGS='--disable-indexing'
2 Likes