Swift-DocC 插件

Swift-DocC 插件是一个 Swift Package Manager 命令行插件，支持为 SwiftPM 库和可执行文件构建文档。

请参阅插件的文档以获取更详细的用法说明。

要将 Swift-DocC 插件与您的软件包一起使用，请首先将其添加为依赖项

let package = Package(
    // name, platforms, products, etc.
    dependencies: [
        // other dependencies
        .package(url: "https://github.com/swiftlang/swift-docc-plugin", from: "1.1.0"),
    ],
    targets: [
        // targets
    ]
)

需要 Swift 5.6 才能运行该插件。

然后，您可以从存储库的根目录调用该插件，如下所示

swift package generate-documentation

这将为您的软件包及其依赖项中定义的所有兼容目标生成文档，并打印生成的 DocC 归档文件的位置。

如果您想为特定目标生成文档并将其输出到特定目录，您可以执行类似以下操作

swift package --allow-writing-to-directory ./docs \
    generate-documentation --target MyFramework --output-path ./docs

请注意，输出路径也必须通过 --allow-writing-to-directory 选项传递给 SwiftPM。否则，SwiftPM 将抛出错误，因为插件在没有明确许可的情况下写入软件包目录是沙箱违规行为。

在 generate-documentation 插件调用之后传递的任何标志都将传递给 docc 命令行工具。例如，要利用 Swift-DocC 对在 GitHub Pages 等静态环境中托管的新支持，您可以运行以下命令

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

Swift-DocC 插件还支持使用本地 Web 服务器预览文档。但是，与转换文档不同，预览仅限于一次预览单个目标。

要预览 MyFramework 目标的文档，您可以运行以下命令

swift package --disable-sandbox preview-documentation --target MyFramework

要预览由您的软件包的依赖项之一定义的产品的文档，您可以运行以下命令

swift package --disable-sandbox preview-documentation --product OtherFramework

有关如何最好地构建文档以进行在线托管以及发布到 GitHub Pages 的具体教程的详细信息，请参阅插件的文档。

Swift-DocC 插件使用 GitHub Issues 跟踪所有错误报告。当您提交错误报告时，我们要求您遵循提供的模板并提供尽可能多的详细信息。

如果您可以确认在使用 main 分支中 Swift-DocC 插件的最新提交时出现错误，这将有助于我们更快地跟踪错误。

对于功能请求，请随时提交 GitHub issue 或在 Swift 论坛上发起讨论。

如果您发现可以改进 Swift-DocC 插件以更好地满足您需求的方法，请不要犹豫提交功能请求。

所有面向用户的功能都必须在 Swift 论坛中讨论后才能默认启用。

有关更多信息，请参阅贡献指南。