Trying to compile private symbol graph for DocC on the web

Development Swift-DocC
1

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
2

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?

3

I am trying to compile a static documentation website

4

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