如何使用 Docc 在 GitHub 上发布？

Question

我在 https://github.com/janodev/foobar 上托管了一个 SPM 软件包。

如何使用 Docc 生成文档并将其托管在 GitHub？

Answer 1

安装Xcode13.3
添加Swift-DocC作为依赖项

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

启用页面发布

在您的 GitHub 存储库中，转到“设置”>“页面”
SelectBranch:main，文件夹：/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

或者，如果软件包包含 iOS 个框架，运行改为：

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"

推送生成的文档

这意味着将 docs 目录推送到 GitHub 存储库。这可能需要一分钟或数分钟，您的浏览器缓存可能会欺骗您，但它应该出现在：

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

请注意，我的存储库名称是小写的，所以我使用了 -hosting-base-path foobar。然而，目标路径组件始终是小写字母，我不知道为什么。

对于任何故障排除，请检查错误数据库：

如何使用 Docc 在 GitHub 上发布？

How can I publish on GitHub using Docc?

ios

swift

swift-package-manager

docc