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 }}CSS assets used by the HTML output format
are processed and generated by PostCSS.
To make changes to these assets,
you'll need to have Node.js
and a package manager, such as npm,
installed on your machine.
Navigate to the .node directory
and run npm install to download the required tools and libraries.
$ cd .node
$ npm install
Note:
package.jsonis located at a hidden.nodesubdirectory to prevent Xcode from displaying or indexing the contents ofnode_moduleswhen opening the main project.
From the .node directory,
run the watch script
to start watching for changes to files in the Assets folder.
Whenever an asset source file is added, removed, or updated,
its corresponding (unoptimized) product is automatically generated
in the Resouces folder.
$ npm run watch
When you're happy with the results,
run the build script to generate production-ready assets.
$ npm run build
Finally,
commit any changes to the source files in Assets
as well as the generated files in Resources.
$ git add Assets Resources
$ git commit
MIT
Mattt (@mattt)