CODEWITHSUNDEEP
iosswiftswift-package-managerdocc
Jano
Jano

Reputation: 63667

How can I publish on GitHub using Docc?

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

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

Upvotes: 3

Views: 1038

Answers (1)

Jano
Jano

Reputation: 63667

  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: [
        // ...
    ]
)
  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:

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

Upvotes: 9

Related Questions