ios - 如何使用 Docc 在 GitHub 上发布？

Question

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

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

Answer 1

1. 安装 Xcode 13.3 beta 1 或 2。不是 Beta 3，因为它与 Swift-DocC 不兼容。
2. 添加 Swift-DocC 作为包的依赖项。它看起来类似于：

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

3. 在 GitHub 中启用页面发布

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

4. 在目录中生成文档./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

swift package \
 --allow-writing-to-directory ./docs \
 --target Foobar \
 generate-documentation \
 --output-path ./docs \
 --transform-for-static-hosting \
 --hosting-base-path foobar

⚠️ 参数值区分大小写。

5. 将生成的文档推送到 repo。

该网站将出现在

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

---

Xcode 13.3 提供了Swift-DocC所需的 Swift 5.6 ，以及将 DocC 用于 iOS 应用程序的能力。但是，在撰写本文时，Swift-DocC 似乎不适用于应用程序。我什至尝试编写一个假包并传递通常的编译器标志来在终端中编译 UIKit（见下文）。这可能会在未来的版本中得到支持。

-Xswiftc "-sdk" -Xswiftc "`xcrun --sdk iphonesimulator --show-sdk-path`" -Xswiftc "-target" -Xswiftc "x86_64-apple-ios15.2-simulator"

如果你得到

Error: The file “data” couldn’t be opened because there is no such file.

记得添加.macOS(.v12)到包的平台。