如何使用 Docc 在 GitHub 上發布？

Question

我有一個 SPM package 托管在https://github.com/janodev/foobar 。

如何使用 Docc 生成文檔並將其托管在 GitHub？

Answer 1

1. 安裝 Xcode 13.3
2. 添加 Swift-DocC 作為依賴項

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

3. 啟用頁面發布

• 在您的 GitHub 存儲庫 go 到設置 > 頁面
• Select 分支：main，文件夾：/docs
• 點擊保存

4. 生成文檔

# 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

或者，如果 package 包含 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"

5. 推送生成的文檔

這意味着將docs目錄推送到 GitHub 存儲庫。 這可能需要一分鍾或數分鍾，您的瀏覽器緩存可能會欺騙您，但它應該出現在：

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

請注意，我的存儲庫名稱是小寫的，所以我使用-hosting-base-path foobar 。 然而，目標路徑組件總是小寫的，我不知道為什么。

---

對於任何故障排除，請檢查錯誤數據庫：

• Swift-文檔
• Swift-DocC-渲染