Repository files navigation

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

Both Swift and Objective-C projects are supported.

Instead of parsing your source files,jazzy hooks intoClang andSourceKit to use theAST representation of your code andits comments for more accurate results. The output matches the look and feelof Apple’s official reference documentation, post WWDC 2014.

Jazzy can also generate documentation from compiled Swift modulesusing theirsymbol graph instead of source code.

This project adheres to theContributor Covenant Code of Conduct.By participating, you are expected to uphold this code. Please reportunacceptable behavior toinfo@realm.io.

You need development tools to build the project you wish to document. Jazzy supportsbothXcode andSwift Package Manager projects.

Jazzy expects to be running onmacOS. Seebelow for tips to run Jazzyon Linux.

[sudo] gem install jazzy

SeeInstallation Problems for solutions to somecommon problems.

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

If your Swift module is the first thing to build, and it builds fine when runningxcodebuild orswift build without any arguments from the root of your project, thenjust runningjazzy (without any arguments) from the root of your project shouldsucceed too!

If Jazzy generates docs for the wrong module then use--module to tell it whichone you'd prefer. If this doesn't help, and you're using Xcode, then try passingextra arguments toxcodebuild, for examplejazzy --build-tool-arguments -scheme,MyScheme,-target,MyTarget.

If you want to generate docs for several modules at once then seeDocumenting multiplemodules.

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 ofall available options, runjazzy --help config.

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'sWriting Symbol Documentation in Your Source Files article.
• Apple'sFormatting Your Documentation Content article.
• Apple'sXcode Markup Formatting Reference.
• Erica Sadun'sSwift header documentation in Xcode 7 post and herbook on Swift Documentation Markup.

For Objective-C documentation the same keywords are supported, but note that the formatis slightly different. In Swift you would write- returns:, but in Objective-C you write@return. See Apple'sHeaderDoc User Guide for more details.Note:jazzy currently does not supportall 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 inbackticks generates a link, for example:

• `MyClass` - a link to documentation forMyClass.
• `MyClass.method(param1:)` - a link to documentation for that method.
• `MyClass.method(...)` - shortcut syntax for the same thing.
• `method(...)` - shortcut syntax to link tomethod from the documentation of anothermethod 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 methodthat appears as justmethod(param1:) in the rendered page.
• ``<doc:method(_:)-e873>`` - a link to a specific overload ofmethod(_:).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 worksapproximately 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` tobe specific. If there is an ambiguity then you can use a leading slash toindicate that the first part of the name should be read as a module name:`/ModuleName.TypeName`.

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 aline 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 byKaTeX.

Swift documentation is generated by default.

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

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

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

...and optionally:

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

For example, this is how theAFNetworking 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-argumentsto pass arbitrary compiler flags. For example, this is how Realm Objective-Cdocs 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)"

Seethe Objective-C docs for more information and some tipson troubleshooting.

This feature has some rough edges.

To generate documentation for a mixed Swift and Objective-C project you must firstgenerate twoSourceKitten files: one for Swift and one for Objective-C.

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

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

# Generate Swift SourceKitten outputsourcekitten doc -- -workspace MyProject.xcworkspace -scheme MyScheme> swiftDoc.json# Generate Objective-C SourceKitten outputsourcekitten 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 listjazzy --module MyProject --sourcekitten-sourcefile swiftDoc.json,objcDoc.json

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

Jazzy can use this to generate API documentation. This is faster than usingthe source code directly but does have limitations: for example documentationcomments are available only forpublic declarations, and the presentation ofSwift 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 bydefault.
2. Same but for iOS:

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

   Thetarget is the LLVM target triple and needs to match the SDK. Thedefault here is the target of the host system that Jazzy is running on,something likex86_64-apple-darwin19.6.0.
3. Generate docs for a personal.swiftmodule:

   jazzy --module MyMod --swift-build-tool symbolgraph      --build-tool-arguments -I,/Build/Products

   This implies that/Build/Products/MyMod.swiftmodule exists. Jazzy's--source-directory (default current directory) is searched by default,so you only need the-I override if that's not enough.
4. For a personal framework:

   jazzy --module MyMod --swift-build-tool symbolgraph      --build-tool-arguments -F,/Build/Products

   This implies that/Build/Products/MyMod.framework exists and containsa.swiftmodule. Again the--source-directory is searched by defaultif-F is not passed in.
5. With pre-generated symbolgraph files:

   jazzy --module MyMod --swift-build-tool symbolgraph      --symbolgraph-directory Build/symbolgraphs

   If you've separately generated symbolgraph files by the use of-emit-symbol-graph, you can pass the location of these files using--symbolgraph-directory from where they can be parsed directly.

Seeswift symbolgraph-extract -help for all the things you can pass via--build-tool-arguments: if your module has dependencies then you may needto add various search path options to let Swift load it.

This feature is new, bugs and feedback welcome

Sometimes it's useful to document multiple modules together in the same site,for example an app and its extensions, or an SDK that happens to be implementedas several modules.

Jazzy can build docs for all these together and create a single site withsearch, cross-module linking, and navigation.

If all the modules share the same build flags then the easiest way to do thisis with--modules, for examplejazzy --modules ModuleA,ModuleB,ModuleC.

If your modules have different build flags then you have to use the config file.For example:

modules:  -module:ModuleA  -module:ModuleBbuild_tool_arguments:      --scheme      -SpecialScheme      --target      -ModuleBsource_directory:ModuleBProject  -module:ModuleCobjc:trueumbrella_header:ModuleC/ModuleC.hframework_root:ModuleCsdk:appletvsimulator  -module:ModuleDsourcekitten_sourcefile:[ModuleD1.json, ModuleD2.json]

This describes a four-module project of which one is 'normal', one requiresspecial Xcode treatment, one is Objective-C, and one has prebuilt SourceKittenJSON.

Per-module options set at the top level are inherited by each module unlessalso set locally -- but you can't set both--module and--modules.

Jazzy doesn't support--podspec mode in conjunction with the multiplemodules feature.

The--merge-modules flag controls how declarations from multiple modulesare arranged into categories.

The default ofall has Jazzy combine declarations from the modules so thereis one category of classes, one of structures, and so on. To the user this meansthey do not worry about which module exports a particular type, although thatinformation remains available in the type's page.

Setting--merge-modules none changes this so each module is a top-levelcategory, with the module's symbols listed under it.

Setting--merge-modules extensions is likenone except cross-moduleextensions are shown as part of their extended type. For example ifModuleAextendsModuleB.SomeType then those extension members fromModuleA are shownon theModuleB.SomeType page along with the rest ofSomeType.

You can use--documentation to include guides,custom_categories to customizethe layout with types from whichever modules you want, and--abstract to addadditional markdown content to the per-module category pages.

Use the--title,--readme-title, and--docset-title flags to control thetop-level names of your documentation. Without these, Jazzy uses the name of oneof the modules being documented.

Three themes are provided with jazzy:apple (default),fullwidth andjony.

• apple example:https://realm.io/docs/swift/latest/api/
• fullwidth example:https://reduxkit.github.io/ReduxKit/
• jony example:https://harshilshah.github.io/IGListKit/

You can specify which theme to use by passing in the--theme option. You canalso provide your own custom theme by passing in the path to your themedirectory.

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 thecustom_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 thereadme option.

You can link to a guide from other guides or doc comments using the name of the pageas it appears in the site. For example, to link to the guide generated from a filecalledMy Guide.md you would write `My Guide`.

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 usingcustom_categories for grouping types and including relevant documentation in those sections.

For an example of a project using both--documentation and--abstract see:https://reswift.github.io/ReSwift/

In Swift mode, Jazzy by default documents onlypublic andopen declarations. Toinclude declarations with a lower access level, set the--min-acl flag tointernal,fileprivate, orprivate.

By default, Jazzy does not document declarations marked@_spi when--min-acl isset topublic oropen. Set the--include-spi-declarations flag to include them.

In Objective-C mode, Jazzy documents all declarations found in the--umbrella-headerheader file and any other header files included by it.

You can control exactly which declarations should be documented using--exclude,--include, or:nodoc:.

The--include and--exclude flags list source files that should be included/excludedrespectively in the documentation. Entries in the list can be absolute pathnames beginningwith/ or relative pathnames. Relative pathnames are interpreted relative to thedirectory from where you runjazzy or, if the flags are set in the config file, relativeto the directory containing the config file. Entries in the list can match multiple filesusing* 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 withInternaland any files under any directory with a name beginningInternal.
• jazzy --exclude=Impl1/*,Impl2/* -- exclude all files under the directoriesImpl1 andImpl2 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 namesthat begin withInternal and any files under any directory with a name beginningInternal,except for those under the directoriesImpl1 andImpl2 found in thecurrent directory

Declarations with a documentation comment containing:nodoc: are excluded from thedocumentation.

Declarations with the@_documentation(visibility:) attribute are treated as though theyare written with the given visibility. You can use this as a replacement for:nodoc: aspart of a transition to Apple's DocC but it is not compatible with Jazzy's symbolgraph mode.

Jazzy arranges documentation into categories. The default categories are thingslikeClasses andStructures corresponding to programming-language concepts,as well asGuides if--documentation is set.

You can customize the categories and their contents usingcustom_categories inthe config file — see the ReSwiftdocs andconfig filefor an example.

Within each category the items are ordered first alphabetically by sourcefilename, and then by declaration order within the file. You can use// MARK: comments within the file to create subheadings on the page, forexample to split up properties and methods. There’s no way to customize thisorder short of editing either the generated web page or the SourceKitten JSON.

Swift extensions and Objective-C categories allow type members to be declaredacross multiple source files. In general, extensions follow the main typedeclaration: first extensions from the same source file, then extensions fromother files ordered alphabetically by filename. Swift conditional extensions(extension A where …) always appear beneath unconditional extensions.

Use this pattern to add or customize the subheading before extension members:

extensionMyType{  // MARK: Subheading for this group of methods…}

When Jazzy is using--swift-build-tool symgraph the source file names andline numbers may not be available. In this case the ordering is approximatelyalphabetical by symbol name and USR; the order is stable for the same input.

Jazzy does not normally create separate web pages for declarations that do nothave any members -- instead they are entirely nested into their parent page. Usethe--separate-global-declarations flag to change this and create pages forthese empty types.

Jazzy normally uses the Swift compiler from the Xcode currently configured byxcode-select. Use the--swift-version flag or theDEVELOPER_DIR environmentvariable to compile with a different Xcode.

The value you pass to--swift-version must be the Swift language version givenbyswift --version in the Xcode you want to use. Jazzy usesxcinvoke to find a suitable Xcodeinstallation on your system. This can be slow: if you know where Xcode isinstalled then it's faster to setDEVELOPER_DIR directly.

For example to use Xcode 14:

jazzy --swift-version 5.7

...or:

DEVELOPER_DIR=/Applications/Xcode_14.app/Contents/Developer jazzy

As well as the browsable HTML documentation, Jazzy creates adocset for usewith theDash app.

By default the docset is created atdocs/docsets/ModuleName.tgz. Use--docset-path to create it somewhere else; use--docset-title to changethe docset's title.

Use--docset-playground-url and--docset-icon to further customize thedocset.

If you set both--root-url to be the (https://) URL where you plan to deployyour documentation and--version to give your documentation a version numberthen Jazzy also creates a docset feed XML file and includes an "Install in Dash"button on the site. This lets users who are browsing your documentation on theweb install and start using the docs in Dash locally.

Jazzy usesSourceKitten to communicate with the Swift buildenvironment and compiler. Thesourcekitten binary included in the Jazzy gemis built for macOS and so does not run on other operating systems.

To use Jazzy on Linux you first need to install and buildsourcekittenfollowing instructions fromSourceKitten's GitHub repository.

Then to generate documentation for a SwiftPM project, instead of running justjazzy do:

sourcekitten doc --spm> doc.jsonjazzy --sourcekitten-sourcefile doc.json

We hope to improve this process in the future.

Only extensions are listed in the documentation?

Check the--min-acl setting -- seeabove.

Unable to find an Xcode with swift version X

1. The value passed with--swift-version must exactly match the versionnumber fromswiftc --version. For example Xcode 10.1 needs--swift-version 4.2.1. Seethe flag documentation.
2. The Xcode you want to use must be in the Spotlight index. You can checkthis usingmdfind '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 theDEVELOPER_DIRenvironment variable to point to the Xcode you want before running Jazzywithout the--swift-version flag.

Seethis document.

Missing docset

Jazzy only builds a docset when you set the--module or--modules flag.

Unable to pass --build-tool-arguments containing commas

If you want Jazzy to run something likexcodebuild -scheme Scheme -destination 'a=x,b=y,c=z'then you must use the config file instead of the CLI flag because the CLI parserthat Jazzy uses cannot handle arguments that themselves contain commas.

The example config file here would be:

build_tool_arguments:  -"-scheme"  -"Scheme"  -"-destination"  -"a=x,b=y,c=z"

Errors running in an Xcode Run Script phase

Running Jazzy from an Xcode build phase can go wrong in cryptic ways when Jazzyhas to runxcodebuild.

Usershave reported that errormessages about symbols lacking USRs can be fixed by unsettingLLVM_TARGET_TRIPLE_SUFFIX as part of the run script.

Warnings about matches and leftovers when using globs and wildcards

Some flags such as--include and--documentation support '*' characters aswildcards. If you are using the CLI then you must make sure that your shelldoes not itself try to interpret them, for example by quoting the token: usejazzy --documentation '*.md' instead ofjazzy --documentation *.md.

Can't find header files / clang

Some of the Ruby gems that Jazzy depends on have native C extensions. Thismeans you need the Xcode command-line developer tools installed to buildthem: runxcode-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 onlywheninstalling Jazzy, not running it.

Starting with Jazzy 0.10.0, if you see an error similar todyld: Symbol not found: _$s11SubSequenceSlTl then you need to install theSwift 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/Applications/Xcode.app.

Please review jazzy'scontributing 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. Installbundler.
2. Runbundle install from the root of this repo.
3. Run jazzy from source by runningbin/jazzy.

Instructions to build SourceKitten from source can be found atSourceKitten'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 theClang AST andSourceKit
• Support for Dash docsets
• Support Swift and Objective-C

This project is released under theMIT license.

Jazzy is maintained and funded by Realm Inc. The names and logos forRealm are trademarks of Realm Inc.

We ❤️ open source software!Seeour other open source projects,readour blog or say hi on twitter(@realm).