jazzy is a command-line utility that generates documentation for Swift or Objective-C

About

Both Swift and Objective-C projects are supported.

Objective-C support was recently added, so please report any issues you find.

Instead of parsing your source files, jazzy hooks into Clang and SourceKit to use the AST representation of your code and its comments for more accurate results. The output matches the look and feel of Apple’s official reference documentation, post WWDC 2014.

Requirements

• A version of Xcode (6.x or 7.x) capable of building the project you wish to document. It must be installed in a location indexed by Spotlight.

Installation

[sudo] gem install jazzy

Usage

Run jazzy from your command line. Run jazzy -h for a list of additional options.

You can set options for your project’s documentation in a configuration file, .jazzy.yaml by default. For a detailed explanation and an exhaustive list of all available options, run jazzy --help config.

Supported keywords

Swift header documentation is written in markdown and supports a number of special keywords. For a complete list and examples, see Erica Sadun’s post on Swift header documentation in Xcode 7.

For Objective-C documentation the same keywords are supported, but note that the format is slightly different. In Swift you would write - returns:, but in Objective-C you write @return. See Apple’s HeaderDoc User Guide for more details. Note: jazzy currently does not support all Objective-C keywords listed in this document.

Swift

Swift documentation is generated by default.

Example

This is how Realm Swift docs are generated:

jazzy \
  --clean \
  --author Realm \
  --author_url https://realm.io \
  --github_url https://github.com/realm/realm-cocoa \
  --github-file-prefix https://github.com/realm/realm-cocoa/tree/v0.96.2 \
  --module-version 0.96.2 \
  --xcodebuild-arguments -scheme,RealmSwift \
  --module RealmSwift \
  --root-url https://realm.io/docs/swift/0.96.2/api/ \
  --output docs/swift_output \
  --template-directory docs/templates

Objective-C

To generate documentation for Objective-C headers, you must pass the following parameters to jazzy: * --objc * --umbrella-header ... * -framework-root ...

Example

This is how Realm Objective-C docs are generated:

jazzy \
  --objc \
  --clean \
  --author Realm \
  --author_url https://realm.io \
  --github_url https://github.com/realm/realm-cocoa \
  --github-file-prefix https://github.com/realm/realm-cocoa/tree/v0.96.2 \
  --module-version 0.96.2 \
  --umbrella-header Realm/Realm.h \
  --framework-root . \
  --module Realm \
  --root-url https://realm.io/docs/objc/0.96.2/api/ \
  --output docs/objc_output \
  --template-directory docs/templates

This is how the AFNetworking docs are generated:

jazzy \
  --objc \
  --author AFNetworking \
  --author_url http://afnetworking.com \
  --github_url https://github.com/AFNetworking/AFNetworking \
  --github-file-prefix https://github.com/AFNetworking/AFNetworking/tree/2.6.2 \
  --module-version 2.6.2 \
  --umbrella-header AFNetworking/AFNetworking.h \
  --framework-root . \
  --module AFNetworking

Troubleshooting

Swift

Only extensions are listed in the documentation?

By default, jazzy only documents public declarations. To generate documentation for declarations with a lower accessibility level (internal or private), please set the --min-acl flag to internal or private.

Development

Please review jazzy’s contributing guidelines when submitting pull requests.

jazzy is composed of two parts:

1. The parser, SourceKitten (written in Swift)
2. The site generator (written in ruby)

To build and run jazzy from source:

1. Install bundler.
2. Run bundle install from the root of this repo.
3. Run jazzy from source by running bin/jazzy.

Instructions to build SourceKitten from source can be found at SourceKitten’s GitHub repository.

Design Goals

• Generate source code docs matching Apple’s official reference documentation
• Support for standard Objective-C and Swift documentation comment syntax
• Leverage modern HTML templating (Mustache)
• Leverage the power and accuracy of the Clang AST and SourceKit
• Support for Dash docsets
• Support Swift and Objective-C (mixed projects are a work in progress)

License

This project is released under the MIT license.