DocC: notes on getting started

DocC solves two different problems. It helps automate API documentation, and it also provides a system for writing support articles and tutorials.

This article is mostly rough notes on the meta of how to view DocC docs, how generate the output and handle the output outside of the XCode ecosystem.

Additional Resources

There are additional resources listed inline with the notes, but here are some not otherwise mentioned but helpful .

WWDC

Misc Others

Getting Help via the Command line

These are the different commands I found:

## stand alone
docc --help
## xcode project related
xcrun docc --help
xcodebuild docbuild -- help
## package
swift package plugin generate-documentation --help

Resources

How to View Your Work

XCode: Open the Documentation Preview

The fastest way to see the results of your DocC work is to use Xcode and open the documentation window (Window > Developer Documentation (Shft-Cmd-0)).

But the most convenient while working on it is to have the Documentation Preview open.

You can access Documentation Preview by first activating the assistant editor via Editor > Assistant, and then selecting “Documentation Preview” in the assistant editor’s jump bar.

To actually build the docs Product > Build Documentation

VSCode

Purportedly when using 6.2 or higher there’s a docc preview available. I haven’t fully checked that out. I could not get it to work when using a swiftly .swift-version file to drive using 6.2

i.e.:

swiftly use 6.2-snapshot-2025-06-12
swiftly run swift package plugin generate-documentation

View a side-by-side live preview of your documentation as you edit it with the Swift extension for VS Code. Access this feature using the Preview Swift Documentation button at the top right of an editor, or be invoking Swift: Preview Documentation in the command palette. This opens up a new editor pane with your rendered documentation:

TODO: check it out with the system’s default toolchain set to 6.2

Package: commandline and a browser.

Using the Package Plugin Directly

Add it to your Package dependencies:

    ],
        dependencies: [
        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
    ],

generate and launch preview:

swift package plugin generate-documentation
swift package --disable-sandbox preview-documentation --target $TARGET_NAME
## or
swift package --disable-sandbox preview-documentation --product $PRODUCT_NAME

Command Line

The docc command for generating an archive is convert. Highly recommend checking out the help to see what’s possible:

which docc
docc convert -- help

The example convert provided is:

docc convert MyNewPackage.docc \
  --fallback-display-name MyNewPackage \
  --fallback-bundle-identifier com.example.MyNewPackage \
  --fallback-bundle-version 1 \
  --additional-symbol-graph-dir .build \
  --output-dir MyNewPackage.doccarchive

So from the package root of my example project:

DocCExplorer % docc convert Sources/DocCExplorer/DocCExplorer.docc \
--fallback-display-name DocCExplorer \
--additional-symbol-graph-dir .build \
--output-dir ~/Desktop/DocCExplorer.doccarchive

Working with an archive

Finding an archive built fo a package

## from the package root folder
## will return both preview builds and output builds
find . -type d -name "*.doccarchive"
## poke around inside
cd .build/plugins/Swift-DocC\ Preview/outputs/$TARGET_NAME.doccarchive
## OR move it
cp -r .build/plugins/Swift-DocC/outputs/$TARGET_NAME.doccarchive $NEW_LOCATION/$TARGET_NAME.doccarchive

What is in an archive

css				
data				
developer-og-twitter.jpg	
developer-og.jpg		
documentation			
downloads			
favicon.ico			
favicon.svg
images
img
index
index.html
js
metadata.json
videos

cd’ing into that dir and running python3 -m http.server $PORT, works, but one will have to navigate by hand down into a subfolder. (that subfolder can be reset see below)

http://localhost:$PORT/documentation/$TARGET_NAME/

What’s interesting is the data folder which will contain json files for all the inline documentation.

The files come out pretty bulky, and seem to use Vue.js to run as an app and webpack to minfy.

One recommended script to “get it ready for static hosting”:

docc process-archive \
transform-for-static-hosting $PATH_TO_DOCCARCHIVE_FILE \
--output-path $PATH_TO_SAVE_FILES \
--hosting-base-path $URL_BASE_PATH

So from the same directory as an example doccarchive file, the below command changed it in place and didn’t change the root directory and got 34 changed files from running:

## in the folder with the doccarchive
docc process-archive \
transform-for-static-hosting ./DocCExplorer.doccarchive \

In the HTML files, which essentially are just light frames for javascript, new js files get swapped in. Because the js files come out all minimized it was irritating to figure out what was different exactly, so I didn’t.

The actual function run is the TransformForStaticHosting command.

Looking at that code it looks like it’s more or less a straight copy when using a --output-path if not also changing the hosting-base-path.