swift-doc

一个用于为 Swift 项目生成文档的软件包。

给定一个 Swift 文件目录，swift-doc 会为每个类、结构体、枚举和协议生成 HTML 或 CommonMark (Markdown) 文件，以及顶层类型别名、函数和变量。

示例输出

要求

Swift 5.3 及以上
libxml2
GraphViz (可选)

命令行实用程序

swift-doc 可以从 macOS 和 Linux 的命令行中使用。

安装

Homebrew

运行以下命令使用 Homebrew 安装

$ brew install swiftdocorg/formulae/swift-doc

如果您已经安装了 swift-doc，请运行以下命令来升级您的安装

$ brew upgrade swift-doc

如果安装或升级失败并显示消息Error: Failed to download resource "swift-doc"，请尝试使用以下命令重置您的安装

$ brew uninstall swift-doc
$ brew untap swiftdocorg/formulae
$ brew install swiftdocorg/formulae/swift-doc

Docker

您可以使用以下命令从最新的 Docker 镜像运行 swift-doc

$ docker pull swiftdoc/swift-doc:latest
$ docker run -it swiftdoc/swift-doc

手动安装

运行以下命令手动构建和安装

$ git clone https://github.com/SwiftDocOrg/swift-doc
$ cd swift-doc
$ make install

如果您使用的是 Ubuntu Linux，可能需要首先运行以下命令来安装先决条件

$ apt-get update
$ apt-get install -y libxml2-dev graphviz

用法

OVERVIEW: A utility for generating documentation for Swift code.

USAGE: swift doc <subcommand>

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

SUBCOMMANDS:
  generate                Generates Swift documentation
  coverage                Generates documentation coverage statistics for Swift
                          files
  diagram                 Generates diagram of Swift symbol relationships

注意：swift 驱动程序通过子命令提供可扩展性。如果您输入一个未知的子命令，例如 swift foo，系统会在您的 PATH 中查找名为 swift-foo 的命令。这种机制允许 swift-doc 直接运行或作为 swift doc 运行。

swift-doc generate

OVERVIEW: Generates Swift documentation

USAGE: swift doc generate [<inputs> ...] --module-name <module-name> [--output <output>] [--format <format>] [--base-url <base-url>]

ARGUMENTS:
  <inputs>                One or more paths to a directory containing Swift files. 

OPTIONS:
  -n, --module-name <module-name>
                          The name of the module 
  -o, --output <output>   The path for generated output (default:
                          .build/documentation)
  -f, --format <format>   The output format (default: commonmark)
  --base-url <base-url>   The base URL used for all relative URLs in generated
                          documents. (default: /)
  --minimum-access-level <minimum-access-level>
                          The minimum access level of the symbols which should
                          be included. (default: public)
  -h, --help              Show help information.

generate 子命令接受一个或多个路径，并递归地枚举它们，将所有 Swift 文件收集到一个“模块”中，并相应地生成文档。任何隐藏目录都会被跳过，包括 .git 和其他以点 (.) 开头的目录。顶层 Tests 目录也会被跳过。

$ swift doc generate path/to/SwiftProject --module-name SwiftProject
$ tree .build/documentation
$ documentation/
├── Home
├── (...)
├── _Footer.md
└── _Sidebar.md

默认情况下，输出文件以 CommonMark / GitHub Wiki 格式写入 .build/documentation，但您可以使用 --output 和 --format 选项标志来更改它。

$ swift doc generate path/to/SwiftProject/Sources --module-name SwiftProject --output Documentation --format html
$ Documentation/
├── (...)
└── index.html

默认情况下，swift-doc 仅在生成的文档中包含声明为 public 或 open 的符号。要包含 internal 或 private 声明，请传递带有指定访问级别的 --minimum-access-level 标志。

swift-doc coverage

OVERVIEW: Generates documentation coverage statistics for Swift files

USAGE: swift doc coverage [<inputs> ...] [--output <output>]

ARGUMENTS:
  <inputs>                One or more paths to a directory containing Swift files.

OPTIONS:
  -o, --output <output>   The path for generated report 
  --minimum-access-level <minimum-access-level>
                          The minimum access level of the symbols which should
                          be included. (default: public)
  -h, --help              Show help information.

coverage 子命令生成 Swift 文件的文档覆盖率统计信息。

$ git clone https://github.com/SwiftDocOrg/SwiftSemantics.git

$ swift run swift-doc coverage SwiftSemantics/Sources --output "dcov.json"
$ cat dcov.json | jq ".data.totals"
{
  "count": 207,
  "documented": 199,
  "percent": 96.1352657004831
}

$ cat dcov.json | jq ".data.symbols[] | select(.documented == false)"
{
  "file": "SwiftSemantics/Supporting Types/GenericRequirement.swift",
  "line": 67,
  "column": 6,
  "name": "GenericRequirement.init?(_:)",
  "type": "Initializer",
  "documented": false
}
...

虽然有很多工具可以评估代码的测试覆盖率，但我们找不到任何与文档覆盖率类似的东西。为此，我们设计了一个简单的 JSON 格式灵感来自 llvm-cov。

如果您知道您认为更适合此目的的现有标准，请通过提出问题来联系我们！

swift-doc diagram

OVERVIEW: Generates diagram of Swift symbol relationships

USAGE: swift doc diagram [<inputs> ...]

ARGUMENTS:
  <inputs>                One or more paths to a directory containing Swift files.

OPTIONS:
  --minimum-access-level <minimum-access-level>
                          The minimum access level of the symbols which should
                          be included. (default: public)
  -h, --help              Show help information.

diagram 子命令以 DOT 格式生成 API 图，可以使用 GraphViz 将其渲染成图表。

$ swift run swift-doc diagram Alamofire/Source > Alamofire.gv
$ head Alamofire.gv
digraph Anonymous {
  "Session" [shape=box];
  "NetworkReachabilityManager" [shape=box];
  "URLEncodedFormEncoder" [shape=box,peripheries=2];
  "ServerTrustManager" [shape=box];
  "MultipartFormData" [shape=box];

  subgraph cluster_Request {
    "DataRequest" [shape=box];
    "Request" [shape=box];

$ dot -T svg Alamofire.gv > Alamofire.svg

这是为 Alamofire 生成的图表的摘录

GitHub Action

此存储库还托管一个 GitHub Action，您可以将其合并到您项目的工作流程中。

swift-doc 生成的 CommonMark 文件已格式化，可以发布到您项目的 GitHub Wiki，您可以使用 github-wiki-publish-action 完成此操作。或者，您可以指定 HTML 格式以将文档发布到 GitHub Pages 或将其捆绑到发布工件中。

输入

inputs：包含您工作区中 Swift (.swift) 文件的目录的路径。（默认值："./Sources"）
format：输出格式（"commonmark" 或 "html"）（默认值："commonmark"）
module-name：模块的名称。
base-url：文档中生成的所有相对 URL 的基本 URL。（默认值："/"）
output：生成的输出的路径。（默认值："./.build/documentation"）

示例工作流程

# .github/workflows/documentation.yml
name: Documentation

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v1
      - name: Generate Documentation
        uses: SwiftDocOrg/swift-doc@master
        with:
          inputs: "Sources"
          module-name: MyLibrary
          output: "Documentation"
      - name: Upload Documentation to Wiki
        uses: SwiftDocOrg/github-wiki-publish-action@v1
        with:
          path: "Documentation"
        env:
          GH_PERSONAL_ACCESS_TOKEN: ${{ secrets.GH_PERSONAL_ACCESS_TOKEN }}

开发

Web 资源

HTML 输出格式使用的 CSS 资源由 PostCSS 处理和生成。要更改这些资源，您需要在您的机器上安装 Node.js 和一个包管理器，例如 npm。

导航到 .node 目录并运行 npm install 来下载所需的工具和库。

$ cd .node
$ npm install

注意：package.json 位于一个隐藏的 .node 子目录中，以防止 Xcode 在打开主项目时显示或索引 node_modules 的内容。

从 .node 目录中，运行 watch 脚本来开始监视 Assets 文件夹中文件的更改。每当添加、删除或更新资源源文件时，其对应的（未优化的）产品会自动在 Sources/swift-doc/Generated 文件夹中生成。

$ npm run watch

当您对结果满意时，请提交对 Assets 中源文件以及 Sources/swift-doc/Generated 中生成文件的任何更改。

$ git add Assets Sources/swift-doc/Generated
$ git commit

发布流程

以下信息主要供项目维护者参考。也就是说，如果您有任何改进此过程的建议，请通过提出问题告诉我们。

按照以下步骤发布 swift-doc 的新版本

验证最新的提交是否通过了所有 CI 检查。
通过为发布创建一个新标题并修改 unreleased 链接引用的最后一个路径组件来更新变更日志。
更新命令行可执行文件中的 version 常量。
创建一个新提交，消息为“Bump version to $VERSION”，其中 $VERSION 是一个 SemVer 兼容版本号。
使用标签名称“$VERSION”标记该提交
运行命令 git push origin master --tags
创建一个与新标签对应的新的发布。

已知问题

直接打开 swift-doc 包时，Xcode 无法运行单元测试 (⌘U)，而不是首先使用 swift package generate-xcodeproj 生成 Xcode 项目文件。（报告的错误是：Library not loaded: @rpath/lib_InternalSwiftSyntaxParser.dylib）。作为一种解决方法，您可以安装最新的工具链并在“Xcode > Preferences > Components > Toolchains”中启用它。或者，您可以从命令行使用 swift test 运行单元测试。

许可证

MIT

联系方式

Mattt (@mattt)