swift-doc is a documentation generator for projects
which are written in the Swift programming language.
It collects all classes, structures, enumerations, and protocols
as well as top-level type aliases, functions, and variables
in a project's Swift source code.
It also reads the comments in the source code
and then renders a documentation
which lists all declared symbols combined with their explanatory comments.
Because of this, swift-doc is the ideal tool to build documentation intended for the users of a Swift library,
but it can also be used to generate the documentation of an iOS or macOS app.
Currently, there are two output formats available:
-
html: Generates a website.
Here you can find an example of SwiftMarkup's documentation rendered as a website.
-
commonmark: Generates markdown files in the CommonMark markdown format. The files generated by
swift-docare build with specific file names and a specific folder structure, so they can be used for publication to your project's GitHub Wiki.Here you can find an example of Alamofire's documentation rendered in a GitHub wiki.
swift-doc only reads the Swift source code of a project.
It does not need to compile or run the project
to generate the documentation.
Because of this, creating documentation with swift-doc is very fast.
And you can run swift-doc on Linux to generate the documentation,
even if the project would require building with Xcode on macOS.
This can simplify building the documentation in your CI pipeline,
because you don't need to execute it on a machine with macOS.
But this approach also comes with some downsides.
As swift-doc only operates on the source code,
it has some limitations:
It can build documentation only for projects that are fully written in Swift.
It can't build documentation for projects which have a codebase that has mixed Objective-C and Swift code.
This guide leads you through all the needed steps to set up swift-doc
to generate a documentation for your project.
It's split into the following parts: