如何使用 Docc 在 GitHub 上发布？

Question

我有一个托管在 的 SPM 包https://github.com/janodev/foobar。

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

Answer 1

\n
1. 安装Xcode 13.3
\n
2. 添加 Swift-DocC 作为依赖项
\n

\n

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

\n

\n
3. 启用页面发布
\n

\n

\n
• 在 GitHub 存储库中，转到“设置”>“页面”
\n
• 选择分支：main，文件夹：/docs
\n
• 单击“保存”
\n

\n

\n
4. 生成文档
\n

\n

# note this is for GitHub hosting, with a specific target and base path \'Foobar\'\n\n# don\xe2\x80\x99t forget to build or you\xe2\x80\x99ll get blank pages\nswift build\n\n# parameter values are case-sensitive!\nswift package \\\n --allow-writing-to-directory ./docs \\\n generate-documentation \\\n --target Foobar \\\n --output-path ./docs \\\n --transform-for-static-hosting \\\n --hosting-base-path foobar\n

\n

或者，如果包包含 iOS 框架，请改为运行以下命令：

\n

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

\n

\n
5. 推送生成的文档
\n

\n

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

\n

#       username          repository           target\nhttps://janodev.github.io/foobar/documentation/foobar\n

\n

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

\n\n

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

\n

\n
• Swift-DocC
\n
• Swift-DocC-渲染
\n

\n