How can I publish on GitHub using Docc?

Question

I have an SPM package hosted at https://github.com/janodev/foobar.

How can I generate documentation with Docc and host it at GitHub?

Answer 1

1. Install Xcode 13.3
2. Add Swift-DocC as a dependency

let package = Package(
    platforms: [
        .iOS(.v15), .macOS(.v12)
    ],
    dependencies: [
        .package(url: "[email protected]:apple/swift-docc-plugin.git", branch: "main"),
    ],
    targets: [
        // ...
    ]
)

3. Enable page publishing

• In your GitHub repository go to Settings > Pages
• Select Branch:main, folder: /docs
• Click Save

4. Generate docs

# note this is for GitHub hosting, with a specific target and base path 'Foobar'

# don’t forget to build or you’ll get blank pages
swift build

# parameter values are case-sensitive!
swift package \
 --allow-writing-to-directory ./docs \
 generate-documentation \
 --target Foobar \
 --output-path ./docs \
 --transform-for-static-hosting \
 --hosting-base-path foobar

Or, if the package contains iOS frameworks, run this instead:

xcodebuild build -scheme Foobar -destination generic/platform=iOS

xcodebuild docbuild -scheme Foobar \
-destination generic/platform=iOS \
OTHER_DOCC_FLAGS="--transform-for-static-hosting --output-path docs --hosting-base-path foobar"

5. Push the generated documentation

This means pushing the docs directory to the GitHub repo. It may take a minute, or several, and your browser cache may deceive you, but it should appear at:

#       username          repository           target
https://janodev.github.io/foobar/documentation/foobar

Note that my repository name was lowercase so I used -hosting-base-path foobar. The target path component, however, is always lowercase, Idk why.

---

For any troubleshooting check the bug database:

• Swift-DocC
• Swift-DocC-Render

This Makefile may be of help generating documentation for a SPM package.