GitHub Action
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
- Swift 5.2
swift-doc can be used from the command-line on macOS and Linux.
Run the following command to install using Homebrew:
$ brew install swiftdocorg/formulae/swift-doc
Run the following commands to build and install manually:
$ git clone https://github.com/SwiftDocOrg/swift-doc
$ cd swift-doc
$ make install
OVERVIEW: A utility for generating documentation for Swift code.
USAGE: swift-doc <subcommand>
OPTIONS:
-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
OVERVIEW: Generates Swift documentation
USAGE: swift-doc generate [<inputs> ...] --module-name <module-name> [--output <output>] [--format <format>]
ARGUMENTS:
<inputs> One or more paths to 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)
-h, --help Show help information.
The generate subcommand
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 --module-name SwiftProject
$ 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 --module-name SwiftProject --output Documentation --format html
$ Documentation/
├── (...)
└── index.html
OVERVIEW: Generates documentation coverage statistics for Swift files
USAGE: swift-doc coverage [<inputs> ...] [--output <output>]
ARGUMENTS:
<inputs> One or more paths to Swift files
OPTIONS:
-o, --output <output> The path for generated report
-h, --help Show help information.
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!
OVERVIEW: Generates diagram of Swift symbol relationships
USAGE: swift-doc diagram [<inputs> ...]
ARGUMENTS:
<inputs> One or more paths to Swift files
OPTIONS:
-h, --help Show help information.
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:
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 specify HTML format publish documentation to
GitHub Pages
or bundle them into a release artifact.
inputs: A path to a directory containing Swift (.swift) files in your workspace. (Default:"./Sources")format: The output format ("commonmark"or"html") (Default:"commonmark")module-name: The name of the module.output: The path for generated output. (Default:"./.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: "Source"
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 }}MIT
Mattt (@mattt)