jazzy is a command-line utility that generates documentation for Swift or Objective-C
Both Swift and Objective-C projects are supported.
SwiftPM 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.
Jazzy expects to be running on macOS. See below for tips to run Jazzy on Linux.
[sudo] gem install jazzy
See Installation Problems for solutions to some common problems.
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
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!
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 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, her book on Swift Documentation Markup, and the Xcode Markup Formatting Reference.
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, and @note.
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.method(param1:)` - a link to documentation for that method.
- `MyClass.method(...)` - shortcut syntax for the same thing.
- `method(...)` - shortcut syntax to link to
methodfrom 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.
Swift documentation is generated by default.
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 \ --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
To generate documentation for Objective-C headers, you must pass the following parameters to jazzy:
--sdk [iphone|watch|appletv][os|simulator]|macosx(optional, default value of
--hide-declarations [objc|swift](optional, hides the selected language declarations)
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/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)"
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
Mixed Objective-C / Swift
This feature is new and has some rough edges.
To generate documentation for a mixed Swift and Objective-C project you must first generate two SourceKitten files: one for Swift and one for Objective-C.
Then pass these files to Jazzy together using
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 --sourcekitten-sourcefile swiftDoc.json,objcDoc.json
Three themes are provided with jazzy:
You can specify which theme to use by passing in the
--theme option. You can also provide your own custom theme by passing in the path to your theme directory.
|Command line option||
By default, jazzy looks for one of README.md, README.markdown, README.mdown or README (in that order) in the directory from where it runs to render the index page at the root of the docs output directory. Using the
--documentation option, extra markdown files can be integrated into the generated docs and sidebar navigation.
Any files found matching the file pattern will be parsed and included as a document with the type 'Guide' when generated. If the files are not included using the
custom_categories config option, they will be grouped under 'Other Guides' in the sidebar navigation.
There are a few limitations:
- File names must be unique from source files.
- Readme should be specified separately using the
Section description abstracts
|Command line option||
--abstract options, extra markdown can be included after the heading of section overview pages. Think of it as a template include.
The list of files matching the pattern is compared against the list of sections generated and if a match is found, it's contents will be included in that section before listing source output.
--documentation option, these files are not included in navigation and if a file does not match a section title, it is not included at all.
This is very helpful when using
custom_categories for grouping types and including relevant documentation in those sections.
For an example of a project using both
--abstract see: https://reswift.github.io/ReSwift/
Controlling what is documented
In Swift mode, Jazzy by default documents only
open declarations. To include declarations with a lower access level, set the
--min-acl flag to
In Objective-C mode, Jazzy documents all declarations found in the
--umbrella-header header file and any other header files included by it.
You can control exactly which declarations should be documented using
--exclude flags list source files that should be included/excluded respectively in the documentation. Entries in the list can be absolute pathnames beginning with
/ or relative pathnames. Relative pathnames are interpreted relative to the directory from where you run
jazzy or, if the flags are set in the config file, relative to the directory containing the config file. Entries in the list can match multiple files using
* to match any number of characters including
/. For example:
jazzy --include=/Users/fred/project/Sources/Secret.swift-- include a specific file
jazzy --exclude=/*/Internal*-- exclude all files with names that begin with Internal and any files under any directory with a name beginning Internal.
jazzy --exclude=Impl1/*,Impl2/*-- exclude all files under the directories Impl1 and Impl2 found in the current directory.
Note that the
--include option is applied before the
--exclude option. For example:
jazzy --include=/*/Internal* --exclude=Impl1/*,Impl2/*-- include all files with names that begin with Internal and any files under any directory with a name beginning Internal, except for those under the directories Impl1 and Impl2 found in the current directory
Declarations with a documentation comment containing
:nodoc: are excluded from the documentation.
Choosing the Swift language version
Jazzy normally uses the Swift compiler from the Xcode currently configured by
xcode-select. Use the
--swift-version flag to compile with a different Xcode.
The value you pass to
--swift-version must be the Swift language version given by
swift --version in the Xcode you want to use.
For example to use Xcode 9.4:
jazzy --swift-version 4.1.2
Jazzy uses SourceKitten to communicate with the Swift build environment and compiler. The
sourcekitten binary included in the Jazzy gem is built for macOS and so does not run on other operating systems.
To use Jazzy on Linux you first need to install and build
sourcekitten following instructions from SourceKitten's GitHub repository.
Then to generate documentation for a SwiftPM project, instead of running just
sourcekitten doc --spm > doc.json jazzy --sourcekitten-sourcefile doc.json
We hope to improve this process in the future.
Only extensions are listed in the documentation?
--min-acl setting -- see above.
Unable to find an Xcode with swift version X
- The value passed with
--swift-versionmust exactly match the version number from
swiftc --version. For example Xcode 10.1 needs
--swift-version 4.2.1. See the flag documentation.
- The Xcode you want to use must be in the Spotlight index. You can check this using
mdfind 'kMDItemCFBundleIdentifier == com.apple.dt.Xcode'. Some users have reported this issue being fixed by a reboot;
mdutil -Emay also help. If none of these work then you can set the
DEVELOPER_DIRenvironment variable to point to the Xcode you want before running Jazzy without the
Can't find header files / clang
Some of the Ruby gems that Jazzy depends on have native C extensions. This means you need the Xcode command-line developer tools installed to build them: run
xcode-select --install to install the tools.
/Applications/Xcode: No such file or directory
The path of your active Xcode installation must not contain spaces. So
/Applications/Xcode.app/ is fine,
/Applications/Xcode-10.2.app/ is fine, but
/Applications/Xcode 10.2.app/ is not. This restriction applies only when installing Jazzy, not running it.
MacOS Before 10.14.4
Starting with Jazzy 0.10.0, if you see an error similar to
dyld: Symbol not found: _$s11SubSequenceSlTl then you need to install the Swift 5 Runtime Support for Command Line Tools.
Alternatively, you can:
- Update to macOS 10.14.4 or later; or
- Install Xcode 10.2 or later at
Please review jazzy's contributing guidelines when submitting pull requests.
jazzy is composed of two parts:
- The parser, SourceKitten (written in Swift)
- The site generator (written in ruby)
To build and run jazzy from source:
- Install bundler.
bundle installfrom the root of this repo.
- Run jazzy from source by running
Instructions to build SourceKitten from source can be found at SourceKitten's GitHub repository.
- 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
This project is released under the MIT license.
Jazzy is maintained and funded by Realm Inc. The names and logos for Realm are trademarks of Realm Inc.