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
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
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!
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 publish swift-doc
-generated documentation to GitHub Pages,
or bundle them into a release artifact.
inputs
: One or more paths to Swift files in your workspace. (Default:"./Sources"
)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"
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)