Jazzy

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

About

Both Swift and Objective-C projects are supported.

Instead of parsing your source files, jazzy hooks into [Clang][clang] and [SourceKit][sourcekit] to use the [AST][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.

Jazzy can also generate documentation from compiled Swift modules using their symbol graph instead of source code.

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to info@realm.io.

Requirements

You need development tools to build the project you wish to document. Jazzy supports both [Xcode][xcode] and [Swift Package Manager][spm] projects.

Jazzy expects to be running on macOS. See below for tips to run Jazzy on Linux.

Installation

[sudo] gem install jazzy

See Installation Problems for solutions to some common problems.

Usage

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

If your Swift module is the first thing to build, and it builds fine when running xcodebuild or swift build without any arguments from the root of your project, then just running jazzy (without any arguments) from the root of your project should succeed too!

If Jazzy generates docs for the wrong module then use --module to tell it which one you'd prefer. If this doesn't help, and you're using Xcode, then try passing extra arguments to xcodebuild, for example jazzy --build-tool-arguments -scheme,MyScheme,-target,MyTarget.

If you want to generate docs for several modules at once then see Documenting multiple modules.

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 documentation keywords

Swift documentation is written in markdown and supports a number of special keywords. Here are some resources with tutorials and examples, starting with the most modern:

• Apple's Writing Symbol Documentation in Your Source Files article.
• Apple's Formatting Your Documentation Content article.
• Apple's Xcode Markup Formatting Reference.
• Erica Sadun's Swift header documentation in Xcode 7 post and her book on Swift Documentation Markup.

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, only @param, @return, @warning, @see, @note, @code, @endcode, and @c.

Jazzy can also generate cross-references within your documentation. A symbol name in backticks generates a link, for example:

• `MyClass` - a link to documentation for MyClass.
• `MyClass.method(param1:)` - a link to documentation for that method.
• `MyClass.method(...)` - shortcut syntax for the same thing.
• `method(...)` - shortcut syntax to link to method from the documentation of another method or property in the same class.
• `[MyClass method1]` - a link to an Objective-C method.
• `-[MyClass method2:param1]` - a link to another Objective-C method.

Jazzy understands Apple's DocC-style links too, for example:

• ``MyClass/method(param1:)`` - a link to the documentation for that method that appears as just method(param1:) in the rendered page.
• ``<doc:method(_:)-e873>`` - a link to a specific overload of method(_:). Jazzy can't tell which overload you intend and links to the first one.

If your documentation is for multiple modules then symbol name resolution works approximately as though all the modules have been imported: you can use `TypeName` to refer to a top-level type in any of the modules, or `ModuleName.TypeName` to be specific. If there is an ambiguity then you can use a leading slash to indicate that the first part of the name should be read as a module name: `/ModuleName.TypeName`.

Math

Jazzy can render math equations written in LaTeX embedded in your markdown:

• `$equation$` renders the equation in an inline style.
• `$$equation$$` renders the equation in a display style, centered on a line of its own.

For example, the markdown:

Inline: `$ax^2+bx+c=0$`

Block: `$$x={\frac {-b\pm {\sqrt {b^{2}-4ac}}}{2a}}$$`

..renders as:

Math support is provided by KaTeX.

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 \
  --source-host github \
  --source-host-url https://github.com/realm/realm-cocoa \
  --source-host-files-url https://github.com/realm/realm-cocoa/tree/v0.96.2 \
  --module-version 0.96.2 \
  --build-tool-arguments -scheme,RealmSwift \
  --module RealmSwift \
  --root-url https://realm.io/docs/swift/0.96.2/api/ \
  --output docs/swift_output \
  --theme docs/themes

This is how docs are generated for a project that uses the Swift Package Manager:

jazzy \
  --module DeckOfPlayingCards \
  --swift-build-tool spm \
  --build-tool-arguments -Xswiftc,-swift-version,-Xswiftc,5

Objective-C

To generate documentation for a simple Objective-C project, you must pass the following parameters:

• --objc
• --umbrella-header ...
• --framework-root ...

...and optionally:

• --sdk [iphone|watch|appletv][os|simulator]|macosx (default value of macosx)
• --hide-declarations [objc|swift] (hides the selected language declarations)

For example, this is how the AFNetworking docs are generated:

jazzy \
  --objc \
  --author AFNetworking \
  --author_url http://afnetworking.com \
  --source-host github \
  --source-host-url https://github.com/AFNetworking/AFNetworking \
  --source-host-files-url https://github.com/AFNetworking/AFNetworking/tree/2.6.2 \
  --module-version 2.6.2 \
  --umbrella-header AFNetworking/AFNetworking.h \
  --framework-root . \
  --module AFNetworking

For a more complicated Objective-C project, instead use --build-tool-arguments to pass arbitrary compiler flags. For example, this is how Realm Objective-C docs are generated:

jazzy \
  --objc \
  --clean \
  --author Realm \
  --author_url https://realm.io \
  --source-host github \
  --source-host-url https://github.com/realm/realm-cocoa \
  --source-host-files-url https://github.com/realm/realm-cocoa/tree/v2.2.0 \
  --module-version 2.2.0 \
  --build-tool-arguments --objc,Realm/Realm.h,--,-x,objective-c,-isysroot,$(xcrun --show-sdk-path),-I,$(pwd) \
  --module Realm \
  --root-url https://realm.io/docs/objc/2.2.0/api/ \
  --output docs/objc_output \
  --head "$(cat docs/custom_head.html)"

See the Objective-C docs for more information and some tips on troubleshooting.

Mixed Objective-C / Swift

This feature has some rough edges.

To generate documentation for a mixed Swift and Objective-C project you must first generate two [SourceKitten][sourcekitten] files: one for Swift and one for Objective-C.

Then pass these files to Jazzy together using --sourcekitten-sourcefile.

Example

This is how docs are generated from an Xcode project for a module containing both Swift and Objective-C files:

# Generate Swift SourceKitten output
sourcekitten doc -- -workspace MyProject.xcworkspace -scheme MyScheme > swiftDoc.json

# Generate Objective-C SourceKitten output
sourcekitten doc --objc $(pwd)/MyProject/MyProject.h \
      -- -x objective-c  -isysroot $(xcrun --show-sdk-path --sdk iphonesimulator) \
      -I $(pwd) -fmodules > objcDoc.json

# Feed both outputs to Jazzy as a comma-separated list
jazzy --module MyProject --sourcekitten-sourcefile swiftDoc.json,objcDoc.json

Docs from .swiftmodules or frameworks

Swift 5.3 added support for symbol graph generation from .swiftmodule files.

Jazzy can use this to generate API documentation. This is faster than using the source code directly but does have limitations: for example documentation comments are available only for public declarations, and the presentation of Swift extensions may not match the way they are written in code.

Some examples:

1. Generate docs for the Apple Combine framework for macOS:

   jazzy --module Combine --swift-build-tool symbolgraph
   

   The SDK's library directories are included in the search path by default.
2. Same but for iOS:

   jazzy --module Combine --swift-build-tool symbolgraph
         --sdk iphoneos
         --build-tool-arguments -target,arm64-apple-ios14.1
   

   The target is the LLVM target triple and needs to match the SD