jazzy is a command-line utility that generates documentation for Swift or Objective-C
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.
This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to [email protected].
- A version of Xcode capable of building the project you wish to
document. It must be installed in a location indexed by Spotlight for the
--swift-version
configuration option to succeed.
[sudo] gem install jazzy
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
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
. - `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.
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 \
--xcodebuild-arguments -scheme,RealmSwift \
--module RealmSwift \
--root-url https://realm.io/docs/swift/0.96.2/api/ \
--output docs/swift_output \
--theme docs/themes
To generate documentation for Objective-C headers, you must pass the following parameters to jazzy:
--objc
--umbrella-header ...
--framework-root ...
--sdk [iphone|watch|appletv][os|simulator]|macosx
(optional, default value ofmacosx
)
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 \
--xcodebuild-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
Two themes are provided with jazzy: apple
(default) and fullwidth
.
Here's an example built with apple
: https://realm.io/docs/swift/latest/api/
Here's an example built with fullwidth
: http://reduxkit.github.io/ReduxKit/
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.
Description | Command |
---|---|
Command line option | --documentation={file pattern} |
Example | --documentation=Docs/*.md |
jazzy.yaml example | documentation: Docs/*.md |
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
readme_path
option.
Description | Command |
---|---|
Command line option | --abstract={file pattern} |
Example | --abstract=Docs/Sections/*.md |
jazzy.yaml example | abstract: Docs/Sections/*.md |
Using the --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.
Unlike the --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 --documentation
and --abstract
see: http://reswift.github.io/ReSwift/
In Swift mode, Jazzy by default documents only public
and open
declarations. To
include declarations with a lower access level, set the --min-acl
flag to internal
,
fileprivate
, or private
.
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 then prevent some of these declarations from being documented using --exclude
or :nodoc:
.
The --exclude
flag lists source files to omit from 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
exclude flag is 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 --exclude=/Users/fred/project/Sources/Secret.swift
-- exclude a specific filejazzy --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.
Declarations with a documentation comment containing :nodoc:
are excluded from the
documentation.
Only extensions are listed in the documentation?
Check the --min-acl
setting -- see above.
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.
- Run
bundle install
from the root of this repo. - Run jazzy from source by running
bin/jazzy
.
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 (mixed projects are a work in progress)
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.
We ❤️ open source software! See our other open source projects, read our blog or say hi on twitter (@realm).