Workspace can generate static HTML documentation for any Swift package.
Workspace is itself a Swift package. You can install it however you want, but make sure you do so with a tagged version (not
master). (You can copy and paste this if you don’t already know what to do.)
Usage is straightforward:
$ cd Path/To/My/Package $ workspace document
Set‐up is easy. The minimal configuration necessary for documentation is this:
// “Workspace.swift” in the package root. import WorkspaceConfiguration let configuration = WorkspaceConfiguration() configuration.documentation.localizations = ["en"]
(The initial load of a configuration is extremely slow, but the result is cached (including intermediates), so subsequent loads are virtually instantaneous. SwiftPM support for target‐based resolution, product caching and mirroring will/can make a huge difference too.)
Documentation‐related features as of Version 0.23.1 include:
- Written in Swift with packages in mind. Built on SwiftPM and SwiftSyntax. (Where relevant, pieces of functionality have even been upstreamed into SwiftPM at times.)
- Fully supports Linux, in addition to macOS. (Its own documentation is self‐generated on Linux in Travis CI.)
Fully comprehends package structure: (See here for a complex example of all of the following.)
- Documents which symbols come from which targets and products.
- Documents only targets reachable through products, ignoring the rest.
- Understands target dependency trees, and lists symbols inherited from package dependencies and core libraries. (But does not republish inherited documentation comments to respect copyright.)
High comprehension of Swift source:
- Documents the
#ifconditions under which a symbol is available.
- Understands overloading and leaves out optimized variants to reduce clutter.
- Understands inheritance:
- Groups symbols according to the superclasses or protocols where they originate.
- Does not require conformances or overrides to be documented. (IDEs like Xcode simply reuse the parent’s documentation anyway.)
- Protocol pages allow filtering conformance requirements, customization points or provided extensions.
- Documents operators and precedence groups.
- Documents the
- Supports some command line interfaces. If the package provides an executable product which uses SDGCommandLine (or just spoofs it), it will be included in the documentation. See Workspace’s own documentation as an example.
Fully supports localization. Symbols can be documented in multiple localizations or redefined in separate localizations. All pages are cross‐referenced between languages.
- English (UK, US, Canada) and German† are already directly supported. See Workspace’s own German documentation as an example. († Proofreading by a native speaker would be welcome.)
- Arbitrary unsupported localizations can still be used, but receive only source‐like headings and navigation, such as saying only
varwhere supported localizations would instead say one of Properties, Eigenschaften, etc.
Contributions are welcome at all levels, but please run any ideas by me in a GitHub issue first. One specific area where I could use some help is improving the appearance of the generated sites.
- Right now, it just mimics the familiar documentation style of the Standard Library and Foundation. It would be grateful if someone more artistic than I am were to liven it up.
- There is no way to customize the appearance (besides overwriting the CSS afterward). A means of customization would also be welcome if it can be designed well.
- The CSS only really targets a computer monitor. Additions or adjustments to better support smartphones would be welcome.
Workspace is licensed under the same Apache 2.0 licence as Swift itself.