I just completed and released a new feature for Workspace. It now has an in‐house documenter designed specifically for packages (it no longer uses Jazzy).
There are still bugs to fix, and I imagine the soon release of Swift 4.2 will throw a wrench in things, but I thought I’d put it out there anyway for anyone else who might already find it useful as‐is, or who wants to pitch in to help find and fix bugs.
Using it is as simple as running this in the package root:
$ workspace document
(Though you would have to configure a localization once first.)
Installation instructions are here, though as a Swift package, you can also use it any way you would another package tool (e.g.
$ swift run workspace ...)
In contrast to Jazzy, this documenter is pure Swift and built on the Swift Package Manager and SwiftSyntax with no reliance on Xcode. This enables it to run on Linux and to understand multi‐target packages and
#if conditions. Since it does not need to build the package, it is fully aware of macOS‐only or Linux‐only symbols even when run on the opposite system.
It has also been designed from the ground up with localized documentation in mind, though that aspect is not complete yet.
However, to give Jazzy the respect it is due—I have used it for years and contributed several bug fixes—, there are some things Jazzy does which Workspace will never do. Jazzy can document Objective C, and it natively deals with Xcode projects. If either of those are important to you, Jazzy will always be your tool of choice.