swift-doc

A package for generating documentation for Swift projects.

Given a directory of Swift files, swift-doc generates HTML or CommonMark (Markdown) files for each class, structure, enumeration, and protocol as well as top-level type aliases, functions, and variables.

Example Output

• HTML
• CommonMark / GitHub Wiki

Requirements

• Swift 5.2

Command-Line Utility

swift-doc can be used from the command-line on macOS and Linux.

Installation

Homebrew

Run the following command to install using Homebrew:

$ brew install swiftdocorg/formulae/swift-doc

Manually

Run the following commands to build and install manually:

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

Usage

swift-doc takes one or more paths and enumerates them recursively, collecting all Swift files into a single "module" and generating documentation accordingly.

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

By default, output files are written to .build/documentation in CommonMark / GitHub Wiki format, but you can change that with the --output and --format option flags.

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

swift-doc coverage

The coverage subcommand generates documentation coverage statistics for Swift files.

$ 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
}
...

While there are plenty of tools for assessing test coverage for code, we weren't able to find anything analogous for documentation coverage. To this end, we've contrived a simple JSON format inspired by llvm-cov.

If you know of an existing standard that you think might be better suited for this purpose, please reach out by opening an Issue!

swift-doc diagram

The diagram subcommand generates a graph of APIs in DOT format that can be rendered by GraphViz into a diagram.

$ swift run swift-doc diagram Alamofire/Source > graph.dot
$ head graph.dot
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 graph.dot > graph.svg

Here's an excerpt of the graph generated for Alamofire:

GitHub Action

This repository also hosts a GitHub Action that you can incorporate into your project's workflow.

The CommonMark files generated by swift-doc are formatted for publication to your project's GitHub Wiki, which you can do with github-wiki-publish-action. Alternatively, you could publish swift-doc-generated documentation to GitHub Pages, or bundle them into a release artifact.

Inputs

• inputs: One or more paths to Swift files in your workspace. (Default: "./Sources")
• output: The path for generated output. (Default: "./.build/documentation")

Example Workflow

# .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: "Source"
          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 }}

License

MIT

Contact

Mattt (@mattt)