1

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

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

Jano
  • 62,815
  • 21
  • 164
  • 192
  • Apple updated DocC to include apps and static hosting. Check out my related answer [here](https://stackoverflow.com/a/71952338/4995828) – Pranav Kasetti Apr 25 '22 at 08:27

1 Answers1

6
  1. Install Xcode 13.3
  2. Add Swift-DocC as a dependency
let package = Package(
    platforms: [
        .iOS(.v15), .macOS(.v12)
    ],
    dependencies: [
        .package(url: "git@github.com:apple/swift-docc-plugin.git", branch: "main"),
    ],
    targets: [
        // ...
    ]
)
  1. Enable page publishing
  • In your GitHub repository go to Settings > Pages
  • Select Branch:main, folder: /docs
  • Click Save
  1. 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"
  1. 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:

Jano
  • 62,815
  • 21
  • 164
  • 192
  • I’m the author of a Swift library that’s available via SPM, and I’ve recently added DocC docs to it. If I want to host these docs on GH Pages and follow your steps, does that mean that anyone using my library then has to download swift-docc-plugin as well? We don’t have “dev dependencies”, right? – Kevin Renskers Mar 26 '22 at 22:29
  • Oh wait, not if I don’t actually add it as a dependency to my target I assume. – Kevin Renskers Mar 26 '22 at 22:32
  • Correct. You add it to the package dependencies but you don’t add it to any target. – Jano Mar 27 '22 at 17:43