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

Both Swift & 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.

jazzy’s output matches the look & feel of Apple’s official reference documentation, post WWDC 2014.

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

To install jazzy, run [sudo] gem install jazzy from your command line.

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.

Swift documentation is generated by default.

As an 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

To generate documentation for Objective-C headers, you should pass --objc, --umbrella-header ... and -framework-root ... as parameters to jazzy.

As an 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

or AFNetworking:

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

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.

jazzy is composed of two parts: the parser (SourceKitten, written in Swift) and the site generator (written in ruby).

To build and run jazzy from source, you'll first need bundler. Once bundler is installed, run bundle install from the root of this repo. At this point, run jazzy from source by running bin/jazzy.

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

jazzy's main design goals are:

• 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 & Objective-C (mixed projects are a work in progress)

This project is under the MIT license.