Soulful docs for Swift & Objective-C

Realm

Last update: Jan 3, 2023

Related tags

Tools ruby swift xcode sourcekit sourcekitten

Overview

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 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 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 [email protected].

Requirements

You need development tools to build the project you wish to document. Jazzy supports both Xcode and Swift Package Manager 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.

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, 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.

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.

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 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 of macosx)
--hide-declarations [objc|swift] (optional, hides the selected language declarations)

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)"

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

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 --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 --sourcekitten-sourcefile swiftDoc.json,objcDoc.json

Docs from `.swiftmodule`s or frameworks

This feature is new and relies on a new Swift feature: there may be crashes and mistakes: reports welcome.

Swift 5.3 adds support for symbol graph generation from .swiftmodule files. This looks to be part of Apple's toolchain for generating their online docs.

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:

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.
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 SDK. The default here is the target of the host system that Jazzy is running on, something like x86_64-apple-darwin19.6.0.
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.
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 contains a .swiftmodule. Again the --source-directory is searched by default if -F is not passed in.
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.

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

Themes

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

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 can also provide your own custom theme by passing in the path to your theme directory.

Guides

Description	Command
Command line option	`--documentation={file pattern}`
Example	`--documentation=Docs/*.md`
jazzy.yaml example	`documentation: Docs/*.md`

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 readme option.

Section description abstracts

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: https://reswift.github.io/ReSwift/

Controlling what is documented

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.

By default, Jazzy does not document declarations marked @_spi when --min-acl is set to public or open. Set the --include-spi-declarations flag to include them.

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, --include, or :nodoc:.

The --include and --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.

Documentation structure

By default Jazzy does not create separate web pages for declarations that do not have any members: instead they are nested into some parent page. Use the --separate-global-declarations flag to change this and always create pages for declarations that can be directly accessed from client code.

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

Linux

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 jazzy do:

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

We hope to improve this process in the future.

Troubleshooting

Swift

Only extensions are listed in the documentation?

Check the --min-acl setting -- see above.

Unable to find an Xcode with swift version X

The value passed with --swift-version must 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 -E may also help. If none of these work then you can set the DEVELOPER_DIR environment variable to point to the Xcode you want before running Jazzy without the --swift-version flag.

Installation Problems

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 /Applications/Xcode.app.

Development

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.

Design Goals

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

License

This project is released under the MIT license.

About

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).

Comments

Problems with Jazzy when multiple versions of Xcode are installed
ERROR: Error installing jazzy: ERROR: Failed to build gem native extension.

/System/Library/Frameworks/Ruby.framework/Versions/2.0/usr/bin/ruby extconf.rb

creating Makefile

make "DESTDIR=" make: *** No rule to make target "/Applications/Xcode', needed byautolink.o'. Stop.

Gem files will remain installed in /Library/Ruby/Gems/2.0.0/gems/redcarpet-3.3.4 for inspection. Results logged to /Library/Ruby/Gems/2.0.0/gems/redcarpet-3.3.4/ext/redcarpet/gem_make.out
bug needs-investigation needs-more-information
opened by GuoZhiQiang 52
Docs for NSError extension (specifically) don't get parsed.
I have some extensions that are all being parsed correctly, for example, this gets detected with no issues and generates valid HTML docs:

public extension String { //MARK: - String Extras /// A capitalized address string. /// e.g. `5TH AVENUE ST` returns `5th Avenue St` public var capitalizedAddress: String {

But specifically my NSError extensions are being skipped for some reason and docs are never generated even though they follow the same format:

public extension NSError { //MARK: - NSError Extras /// Return a `THResponse` object corresponding to the current `NSError`. public var asResponse: THResponse { ... ...

This is how it looks:

This is even weirder since jazzy outputs parsing of the file, but doesn't generate the docs from it e.g. Parsing NSError.Exts.swift (27/47) .

Would appreciate any help on this !

Kind Regards, Shai.
bug
opened by freak4pc 34

Handle projects with no documentation comments

Using jazzy v0.0.14 and ruby 2.1.5 on Yosemite installed via Homebrew I get a JSON parsing error and then a whole bunch of JSON code printed to console.

my-swift-prj$ jazzy
Running xcodebuild -dry-run
parsing Xyz.swift (1/n)
Xyz.swift is 40% documented
[...]
building site
/usr/local/Cellar/ruby/2.1.5/lib/ruby/2.1.0/json/common.rb:155:in `parse': 399: unexpected token at ',  (JSON::ParserError)
[...]
'
    from /usr/local/Cellar/ruby/2.1.5/lib/ruby/2.1.0/json/common.rb:155:in `parse'
    from /usr/local/lib/ruby/gems/2.1.0/gems/jazzy-0.0.14/lib/jazzy/sourcekitten.rb:162:in `parse'
    from /usr/local/lib/ruby/gems/2.1.0/gems/jazzy-0.0.14/lib/jazzy/doc_builder.rb:94:in `build_docs_for_sourcekitten_output'
    from /usr/local/lib/ruby/gems/2.1.0/gems/jazzy-0.0.14/lib/jazzy/doc_builder.rb:51:in `build'
    from /usr/local/lib/ruby/gems/2.1.0/gems/jazzy-0.0.14/bin/jazzy:15:in `<top (required)>'
    from /usr/local/bin/jazzy:23:in `load'
    from /usr/local/bin/jazzy:23:in `<main>'

Ideas?

feature

opened by juangamnik 29

Support Xcode 6 GM
Unfortunately, the approach we took with Xcode 6 Betas 1 & 2 no longer work with Beta 3.

This still works:

$ xcrun sourcekitd-test -req doc-info SwiftFile.swift

but this no longer works:

$ xcrun sourcekitd-test -req doc-info -module MyModule -- -I `pwd` -sdk `xcrun --show-sdk-path` sourcekit: [1:connection-event-handler:271: 0.0000] Connection interrupt sourcekit: [1:pingService:271: 0.0016] pinging service error response (Connection Interrupted): Connection interrupted

Seems to be an issue with sourcekitd-test's XPC connection with SourceKitService, but I'm unsure how to fix it. If anyone has any ideas, I'd :heart: to hear from you!
enhancement feature
opened by jpsim 29
jazzy version: 0.7.0, can't get --exclude to ignore files

Putting in the full file spec / path / name but jazzy is still include the file / class in the docs

Have tried /*, /filename.swift, etc.

Any help would be appreciated.
needs-investigation needs-more-information

opened by ort11 28

Generating doc for Obj-C project

I'm trying to generate the documentation for an ObjC framework.

Unfortunately, I cannot make Jazzy work.

The framework is part of a workspace, so I'm trying to use the xcodebuild-arguments option as follow:

jazzy \
  --objc \
  --clean \
  --xcodebuild-arguments -scheme,MyScheme,-workspace,MyWorkspace \
  --output docs/

But I'm getting the following error:

Unrecognized arguments: -schem, -workspace
/Users/bruno/Downloads/jazzy/lib/jazzy/executable.rb:36:in `execute_command': /Users/bruno/Downloads/jazzy/bin/sourcekitten ["doc", "-scheme", "MyScheme", "-workspace", "MyWorkspace"] (RuntimeError)

Unrecognized arguments: -schem, -workspace
	from /Users/bruno/Downloads/jazzy/lib/jazzy/sourcekitten.rb:230:in `run_sourcekitten'
	from /Users/bruno/Downloads/jazzy/lib/jazzy/doc_builder.rb:66:in `block in build'
	from /Users/bruno/Downloads/jazzy/lib/jazzy/doc_builder.rb:64:in `chdir'
	from /Users/bruno/Downloads/jazzy/lib/jazzy/doc_builder.rb:64:in `build'
	from /Users/bruno/Downloads/jazzy/bin/jazzy:15:in `<main>'

It looks like at some point the arguments are cut out (scheme becomes schem). Not sure why? And even without considering that, -workspace is presented as an unrecognized arguments.

Do you know what could be the issue here?

Also a more general question: is generating documentation for an Objective-C framework still supported?

Thanks a lot!

documentation

opened by bvirlet 26

Undocumented APIs can output as structured JSON
When provided, a tab-separated table of linter-specific results will be written to the file. If a relative path is provided, the path will be considered relative to the current working directory.

Report format

The first column of each row defines the report type.

The number of additional columns is dependent on the report type.

The contents of each report type are outlined below (commas represent tabs):

<report type>, <columns> undocumented, full_path, line_number, symbol, symbol_type

This PR removes the undocumented.txt file output in favor of the lint-report output.

The intent of this option is to enable a linting engine to communicate with jazzy. Future linting results should be possible using the "report type" field that precedes each column.
feature github-review-accepted
opened by jverkoey 26

Library not loaded: @rpath/libswiftCore.dylib sourcekitten

I did uninstall of jazzy, updated gem, but nothing working

dyld: Library not loaded: @rpath/libswiftCore.dylib
  Referenced from: /usr/local/var/rbenv/versions/2.1.5/lib/ruby/gems/2.1.0/gems/jazzy-0.1.0/lib/jazzy/sourcekitten/sourcekitten
  Reason: image not found
/usr/local/var/rbenv/versions/2.1.5/lib/ruby/gems/2.1.0/gems/jazzy-0.1.0/lib/jazzy/sourcekitten.rb:51:in `run_sourcekitten': Running `/usr/local/var/rbenv/versions/2.1.5/lib/ruby/gems/2.1.0/gems/jazzy-0.1.0/lib/jazzy/sourcekitten/sourcekitten doc` failed:  (RuntimeError)
    from /usr/local/var/rbenv/versions/2.1.5/lib/ruby/gems/2.1.0/gems/jazzy-0.1.0/lib/jazzy/doc_builder.rb:55:in `build'
    from /usr/local/var/rbenv/versions/2.1.5/lib/ruby/gems/2.1.0/gems/jazzy-0.1.0/bin/jazzy:15:in `<top (required)>'
    from /usr/local/var/rbenv/versions/2.1.5/bin/jazzy:23:in `load'
    from /usr/local/var/rbenv/versions/2.1.5/bin/jazzy:23:in `<main>'

question

opened by maltzsama 24

Add support for Jazzy for code where a Xcode project doesn't exist

I have a Swift project that is not a Xcode project, it is a RemObjects Fire project - https://github.com/loretoparisi/swift-promise-example. If I try to run jazzy from the sources folder src/ (that is here: https://github.com/loretoparisi/swift-promise-example/tree/master/StaticLibrary/SharedProject/src ) I get an error that I suppose is due to the fact that this is not a Xcode project:

Running xcodebuild

Could not parse compiler arguments from `xcodebuild` output.

Please confirm that `xcodebuild` is building a Swift module.

Saved `xcodebuild` log file: /var/folders/mm/qbx_84b57sgf_f9j0cxmj__r0000gn/T/xcodebuild-FAD08B0F-059E-415B-968E-D4074BD7D21D.log

Failed to generate documentation
    from /Library/Ruby/Gems/2.0.0/gems/jazzy-0.5.0/lib/jazzy/sourcekitten.rb:140:in `run_sourcekitten'
    from /Library/Ruby/Gems/2.0.0/gems/jazzy-0.5.0/lib/jazzy/doc_builder.rb:57:in `block in build'
    from /Library/Ruby/Gems/2.0.0/gems/jazzy-0.5.0/lib/jazzy/doc_builder.rb:55:in `chdir'
    from /Library/Ruby/Gems/2.0.0/gems/jazzy-0.5.0/lib/jazzy/doc_builder.rb:55:in `build'
    from /Library/Ruby/Gems/2.0.0/gems/jazzy-0.5.0/bin/jazzy:15:in `<top (required)>'
    from /usr/bin/jazzy:23:in `load'
    from /usr/bin/jazzy:23:in `<main>

So is it possibile to run jazzy for non Xcode projects?

feature

opened by loretoparisi 23

Xcode 7.1

Is there support for Xcode 7.1 yet? Can't get anything documented, maybe I am missing something.

This is what I am seeing. Im sure my comments are formatted correctly

enhancement question

opened by gsapienza 23

[0.13.3] Could not parse compiler [...] - codesign disable flags missing

Version 0.13.3 broke for my project: https://github.com/jessesquires/PresenterKit

Version 0.13.2 works. So this seems to be a regression.

Script (also here)

PROJECT="PresenterKit"

jazzy \
    --clean \
    --author "Jesse Squires" \
    --author_url "https://jessesquires.com" \
    --github_url "https://github.com/jessesquires/$PROJECT" \
    --module "$PROJECT" \
    --source-directory . \
    --readme "README.md" \
    --documentation "Guides/*.md" \
    --output docs/

Output using `0.13.3`

Running xcodebuild
Checking xcodebuild -showBuildSettings
Running xcodebuild
Could not parse compiler arguments from `xcodebuild` output.
Please confirm that `xcodebuild` is building a Swift module.
Saved `xcodebuild` log file: /var/folders/tx/s__fjnns3yd_23813_gwk7sh0000gn/T/xcodebuild-3AF8CAD1-53FA-4525-B8BF-C55AA351764D.log
Failed to generate documentation
Traceback (most recent call last):
	7: from /usr/local/var/rbenv/versions/2.6.5/bin/jazzy:23:in `<main>'
	6: from /usr/local/var/rbenv/versions/2.6.5/bin/jazzy:23:in `load'
	5: from /usr/local/var/rbenv/versions/2.6.5/lib/ruby/gems/2.6.0/gems/jazzy-0.13.3/bin/jazzy:15:in `<top (required)>'
	4: from /usr/local/var/rbenv/versions/2.6.5/lib/ruby/gems/2.6.0/gems/jazzy-0.13.3/lib/jazzy/doc_builder.rb:76:in `build'
	3: from /usr/local/var/rbenv/versions/2.6.5/lib/ruby/gems/2.6.0/gems/jazzy-0.13.3/lib/jazzy/doc_builder.rb:76:in `chdir'
	2: from /usr/local/var/rbenv/versions/2.6.5/lib/ruby/gems/2.6.0/gems/jazzy-0.13.3/lib/jazzy/doc_builder.rb:78:in `block in build'
	1: from /usr/local/var/rbenv/versions/2.6.5/lib/ruby/gems/2.6.0/gems/jazzy-0.13.3/lib/jazzy/sourcekitten.rb:266:in `run_sourcekitten'
/usr/local/var/rbenv/versions/2.6.5/lib/ruby/gems/2.6.0/gems/jazzy-0.13.3/lib/jazzy/executable.rb:36:in `execute_command': /usr/local/var/rbenv/versions/2.6.5/lib/ruby/gems/2.6.0/gems/jazzy-0.13.3/bin/sourcekitten ["doc", "--module-name", "PresenterKit", "--"] (RuntimeError)

Running xcodebuild

Checking xcodebuild -showBuildSettings

Running xcodebuild

Could not parse compiler arguments from `xcodebuild` output.

Please confirm that `xcodebuild` is building a Swift module.

Saved `xcodebuild` log file: /var/folders/tx/s__fjnns3yd_23813_gwk7sh0000gn/T/xcodebuild-3AF8CAD1-53FA-4525-B8BF-C55AA351764D.log

Failed to generate documentation

bug

opened by jessesquires 22

objc method produces multiple methods in generated swift interface but jazzy ignores some of them

Example:

NS_ASSUME_NONNULL_BEGIN
typedef void(^SomeCompletion)(NSString * _Nullable str);

@interface SomeClass: NSObject
- (void)loadTokenWithCompletionHandler:(SomeCompletion)completionHandler;
@end
NS_ASSUME_NONNULL_END

Generated swift file:

public typealias SomeCompletion = (String?) -> Void

open class SomeClass : NSObject {
open func loadToken(completionHandler: @escaping SomeCompletion)
open func loadToken() async -> String?
}

Generated documentation contains description of open func loadToken() async -> String? only which is even less intuitive.

bug sourcekitten

opened by gerchicovy 1

Cannot build docs from podspec with unpublished dependency pod
We have multiple cocoapods in our repository called Stripe and StripeCore. The Stripe pod depends on the StripeCore pod of the same version (e.g. [email protected] depends on [email protected]).

When we deploy a new version of our pod, our deployment process is to:

Bump our podspec version numbers

Generate docs using Jazzy

Merge the updated podspec & docs to our repo & tag the commit

pod trunk push StripeCore

pod trunk push Stripe

When we generate our docs, the current version of our StripeCore pod is not yet published. So Jazzy produces something like the following error (in this example, the version is 100.0.0):

[!] CocoaPods could not find compatible versions for pod "StripeCore": (Pod::NoSpecFoundError) In Podfile: Stripe (from `/Users/mludowise/stripe/stripe-ios-private`) was resolved to 100.0.0, which depends on StripeCore (= 100.0.0) None of your spec sources contain a spec satisfying the dependency: `StripeCore (= 100.0.0)`. You have either: * out-of-date source repos which you can update with `pod repo update` or with `pod install --repo-update`. * mistyped the name or version. * not added the source repo that hosts the Podspec to your Podfile.

Steps to reproduce:

git clone [email protected]:stripe/stripe-ios.git && cd stripe-ios && checkout origin/mludowise/pod_dependency_jazzy_example

I bumped the podspec version in this branch to 100.0.0 since that won't be published to CP any time soon

jazzy --config .jazzy.yaml --github-file-prefix "https://github.com/stripe/stripe-ios/tree/100.0.0" --podspec Stripe.podspec

This is the git branch with the example: https://github.com/stripe/stripe-ios/tree/mludowise/pod_dependency_jazzy_example

Proposal

Ideally, there would be a way to specify to Jazzy a list of local .podspec files to use as dependencies rather than fetching from pod trunk. Perhaps something like:

jazzy --podspec Stripe.podspec --include-podspecs StripeCore.podspec,/path/to/AnotherPod.podspec,...

The resulting podspec files could be included in the generated podfile inside podspecdocumenter.rb like:

pod 'MyPod', path: '/path/to/mypod/' pod 'DependencyPod', path: '/path/to/dependencypod/'

Cocoapods uses an --include-podspecs flag as an option for pod lib lint to lint against local podspec files, so there's precedence for the name.

Workaround

For anyone else running into this issue, we devised a workaround for the dependency issue by creating a local git spec repo that contains .podspec files for our dependency pods with file:// URLs for their s.source value. Then we pass that generated spec repo to jazzy using the --pod-sources option. It's certainly not ideal, but it seems to function for the time being.

Script for creating a temp spec repo: https://github.com/stripe/stripe-ios/blob/mludowise/pod_dependency_jazzy_example/ci_scripts/make_temp_spec_repo.sh

Used by our docs generation here: https://github.com/stripe/stripe-ios/blob/mludowise/pod_dependency_jazzy_example/ci_scripts/build_documentation.sh#L49 To

enhancement
opened by mludowise-stripe 1
Add support for ingesting DocC archives or JSON as input

Instead of passing in a SourceKitten JSON file, jazzy could ingest a DocC archive or the JSON file(s) embedded within as input.

This could help users who've invested in custom themes or other jazzy features over the years get the benefits of using DocC as the documentation collection part of the pipeline.

I'm attaching the Yams DocC documentation archive as generated by Xcode 13 beta 1 which we can use as a reference. Yams.doccarchive.zip

The JSON files under data/documentation seem to have everything we currently get from SourceKitten. There seems to be a JSON file for every declaration included in the documentation, but it might be sufficient to just read the JSON file at the root (e.g. Yams.doccarchive/data/documentation/yams.json) I'm not sure yet.

Obviously with DocC being (currently) closed source and this JSON format likely being in flux and subject to change at any time, we probably can't rely on the exact format staying stable, but this can still be worthwhile even with that risk.
enhancement

opened by jpsim 3
Support for C++ files?

I suspect the answer is "no" but perhaps there is some magic collection of xcodebuild options that others have uncovered that I can use to extract docs from C++ files. Right now, I have jazzy processing Swift files in my project, and I have doxygen doing the C++ files, storing them in separate directories.
enhancement sourcekitten

opened by bradhowes 1
Generate Sitemap

I don't see any options to generate a Sitemap and I thought it would be a very interesting feature to add to Jazzy.

As most people type their questions into Google, letting search engines discover all the pages could help.

Since sitemaps are XML files, it would fairly easy to generate.
enhancement

opened by arguiot 0
Add ability to force-show certain undocumented types even with `skip_undocumented`

I want to use skip_undocumented: true to skip undocumented types. However, I have a Swift enum with a large amount of casees and they don't really need to be documented as their name makes it clear enough. It would be nice to be able to use some kind of code comment to indicate that I don't want to exclude those undocumented enum cases (without having to add it to each case).
enhancement

opened by sindresorhus 2

Releases(v0.14.3)

v0.14.3(Sep 11, 2022)
Breaking

None.

Enhancements

Support Swift 5.7 and Xcode 14. John Fairhurst

Update Javascript: jQuery 3.6.1, KaTeX 0.13.5 John Fairhurst

Bug Fixes

None.

Source code(tar.gz)
Source code(zip)
v0.14.2(Mar 17, 2022)
Breaking

When building with Swift 5.6 and not passing —-module to Jazzy, declarations may not be correctly identified as undocumented and docs may include unwanted extensions. Pass —-module MyModuleName to fix this. John Fairhurst

Enhancements

Support using pre-generated symbolgraph files in Swift symbolgraph mode. Nathan Wong

Issue a warning on some combinations of Objective-C flags. John Fairhurst #900

Support Swift 5.6. The bundled sourcekitten is a universal binary. John Fairhurst

Bug Fixes

In Swift symbolgraph mode, stop including extensions to types that are beneath the minimum ACL. John Fairhurst #1291

Source code(tar.gz)
Source code(zip)
v0.14.1(Oct 4, 2021)
Breaking

Support Swift SPI groups. Swift declarations marked @_spi are no longer included in docs when --min-acl is set to public or open. Use --include-spi-declarations to include docs for these declarations. John Fairhurst #1263

Enhancements

Correct line number references with Xcode 13. John Fairhurst

Support union declarations in Objective-C headers. Brian Osborn John Fairhurst

Support Swift concurrency features: identify actors and asynchronous methods. John Fairhurst

Bug Fixes

Improve HTML5 correctness, all themes. John Fairhurst #1280

Source code(tar.gz)
Source code(zip)
v0.14.0(Aug 14, 2021)
Breaking

Require at least Ruby 2.6.3.

Enhancements

Support DocC-style autolinks and callouts in markdown. John Fairhurst

Add --source-host option to support projects hosted on GitLab and Bitbucket as well as GitHub. Options --source-host-url and --source-host-files-url and new Mustache tags replace the 'github' versions which remain as back-compatibility aliases. John Fairhurst #314

Add rel="noopener" to all target="_blank" links. JP Simard

Bug Fixes

Fix source-host line number references in Swift symbolgraph mode, and in ObjC mode for references to one-line declarations. John Fairhurst

Fix crash with ` ` in markdown. John Fairhurst #1270

Fix symbolgraph mode with Xcode 13. John Fairhurst

Source code(tar.gz)
Source code(zip)
v0.13.7(May 6, 2021)
0.13.7

The next release of Jazzy will require a minimum of Ruby 2.6.

Breaking

None.

Enhancements

Update JavaScript libraries: jQuery 3.6.0, Lunr 2.3.9, KaTeX 0.13.5.
John Fairhurst

Support the markdown footnotes extension in all themes.
John Fairhurst #1246

Bug Fixes

Fix parameter doc comments in Swift symbolgraph mode.
John Fairhurst #1244

Source code(tar.gz)
Source code(zip)
v0.13.6(Nov 8, 2020)
Breaking

None.

Enhancements

Support documentation generation from .swiftmodule binaries using --swift-build-tool symbolgraph with Swift 5.3. John Fairhurst

Bug Fixes

Always bypass codesigning when building Xcode projects. John Fairhurst #1183

Source code(tar.gz)
Source code(zip)
v0.13.5(Jul 6, 2020)
Breaking

None.

Enhancements

Add search function to apple theme. Giles Payne #726

Add option --[no-]separate-global-declarations to always create separate documentation pages for top-level declarations as well as classes, structures, enums etc. even if they don't have members. As part of this, improve the main page declaration in all modes. Nikolay Volosatov John Fairhurst

Bug Fixes

Style fixes for apple and jony themes to codeblocks inside lists and links. John Fairhurst #818 #1177

Source code(tar.gz)
Source code(zip)
v0.13.4(May 31, 2020)
Breaking

None.

Enhancements

Update JavaScript libraries: jQuery 3.5.1 (all themes), Lunr 2.3.8, typeahead.js 1.3.1 (fullwidth theme only). John Fairhurst

Bug Fixes

Fix warnings from Ruby 2.7. John Fairhurst #1185

Accept root_url without trailing slash. John Fairhurst #1188

Source code(tar.gz)
Source code(zip)
v0.13.3(Apr 24, 2020)
Breaking

None.

Enhancements

Added a config option to provide sources of privately hosted pod dependencies when using the --podspec option. --pod-sources url1,url2,…urlN. Jonathan Bailey #650

Improve Dash docset support: support online redirection when --root-url is set, and provide --docset-playground-url to support docset playground links. John Fairhurst

Bug Fixes

Fix module version not being used from podspec. Jonathan Bailey

Autolink Swift custom attributes/property wrappers. John Fairhurst

Source code(tar.gz)
Source code(zip)
v0.13.2(Apr 2, 2020)
Breaking

None.

Enhancements

Support Xcode 11.4. Default Objective-C property attributes are now stripped from declarations: turn this off with --keep-default-property-attributes. John Fairhurst #829

Render LaTeX expressions written using $equation$ or $$equation$$ syntax. Arthur Guiot John Fairhurst #1156

Wrap long method names on category pages. Use name_html in custom mustache templates to take advantage of this. John Fairhurst #995

Support Dash-style apple_ref links to specific API items, for more stable and human-readable links from external docs. Paul Cantrell #1167

Bug Fixes

Don't generate documentation if the xcodebuild command fails. John Fairhurst jpsim/SourceKitten#643

Use multi-line parsed declarations in more places including protocol methods and typealiases. John Fairhurst #896

Source code(tar.gz)
Source code(zip)
v0.13.1(Jan 7, 2020)
Breaking

None.

Enhancements

Allow inline html tags in ObjC doc comments.
Chris Williams #976

Support code formatting in ObjC doc comments with @c, @code and @endcode.
Bryce Pauken jpsim/SourceKitten#631

Add custom_categories_unlisted_prefix configuration setting. This is the prefix for navigation section names that aren't explicitly listed in custom_categories. Defaults to 'Other '.
JP Simard

Add hide_unlisted_documentation configuration setting. Setting this to true hides documentation entries in the sidebar from the documentation config value that aren't explicitly listed in custom_categories.
JP Simard

Bug Fixes

Fix crash when SourceKit returns out of bounds string byte offsets.
JP Simard

Pick the right version of declarations with type attributes.
John Fairhurst #1148

Source code(tar.gz)
Source code(zip)
v0.13.0(Dec 9, 2019)
Breaking

None.

Enhancements

Add section headings for members added by Swift conditional conformances. John Fairhurst #717

Parse markdown in MARK comments, make the html available to themes via name_html mustache tag key for section headings. John Fairhurst

Include protocol conformances added by extensions in Swift docs. John Fairhurst

Bug Fixes

Render bullet lists correctly when followed by a callout. John Fairhurst #785

Render markup of text inside double quotes. John Fairhurst #992

Fix sourcekitten_sourcefile used from config file. John Fairhurst #1137

Source code(tar.gz)
Source code(zip)
v0.12.0(Nov 11, 2019)
Breaking

None.

Enhancements

Support for mixed Swift-ObjC modules: generate two sets of SourceKitten json and pass them on using --sourcekitten-sourcefile. Joe Susnick John Fairhurst #447

Bug Fixes

Stop displaying type attributes on extension declarations. John Fairhurst

Show ObjC and Swift classes (etc.) in the same category. John Fairhurst

Merge Swift extensions into ObjC classes. John Fairhurst Joe Susnick

Source code(tar.gz)
Source code(zip)
v0.11.2(Sep 25, 2019)
Breaking

None.

Enhancements

None.

Bug Fixes

Generate Swift docs with Xcode 11 and paths with spaces. John Fairhurst #1108

Reinstate guessing of module name from podspec, broken in 0.11.0. John Fairhurst #1109

Source code(tar.gz)
Source code(zip)
v0.11.1(Sep 17, 2019)
Breaking

None.

Enhancements

None.

Bug Fixes

Don't use SwiftPM if there is an Xcode workspace or project in a non-root directory.
John Fairhurst #1103

Source code(tar.gz)
Source code(zip)
v0.11.0(Sep 14, 2019)
Breaking

None.

Enhancements

Sass support now provided by libsass via sassc instead of the deprecated Ruby Sass gem.
John Fairhurst

Update bundled jQuery to 3.4.1 (all themes).
Paul Idstein

Support Xcode 11 Swift projects that pass a response file to the Swift compiler.
John Fairhurst #1087

Generate Swift docs from a Swift Package Manager package without requiring an Xcode project file. Add --swift-build-tool to choose the build method if both .xcodeproj and Package.swift files are present. Add --build-tool-flags as a preferred alias for --xcodebuild-flags.
John Fairhurst #487

Bug Fixes

Preserve non-latin characters in guide filenames and heading IDs.
John Fairhurst #1091

Generate correct html for custom categories containing special characters.
John Fairhurst #945

Fix crash on files with misplaced documentation comments.
John Fairhurst #1083

Source code(tar.gz)
Source code(zip)
v0.10.0(Jun 22, 2019)
Breaking

The included sourcekitten binary is built with Xcode 10.2. This means it does not run on macOS earlier than 10.14.4 without the Swift 5 Runtime Support for Command Line Tools being installed. John Fairhurst

Enhancements

Support CocoaPods 1.6+. Use the swift_version[s] dsl in --podspec mode to set the Swift language version. John Fairhurst

Show the extension declaration when documenting Swift extensions. John Fairhurst

Allow docs title customization. Include --module-version when it is set and support --title to fully customize the title. Pass {{module_version}} and {{docs_title}} to templates. Maximilian Alexander John Fairhurst #666 #411

Bug Fixes

Unfold member documentation when linked to from current web page. John Fairhurst #788

Generate docs when there are unusual characters in source pathnames. John Fairhurst #1049

Generate docs for signed modules with Xcode 10.2. John Fairhurst #1057

Use correct module name when only target name is supplied. Chris Zielinski #422

Source code(tar.gz)
Source code(zip)
v0.9.6(Apr 4, 2019)
This is (probably) the last release to support Ruby earlier than 2.3. This is due to a change in a dependency.

This is (probably) the last release to support macOS earlier than 10.14.4 without the Swift 5 Runtime Support for Command Line Tools package installed. This is a consequence of Swift 5 ABI stability.

Breaking

None.

Enhancements

Swift 5 support: suppress unwanted newlines and deinit declarations. John Fairhurst

Update JavaScript libraries: jQuery 3.3.1 (all themes), Lunr 2.3.5, typeahead.js 1.2.1 (fullwidth theme only). John Fairhurst #901

Avoid clean build when using the new Xcode build system. Norio Nomura

Bug Fixes

None.

Source code(tar.gz)
Source code(zip)
v0.9.5(Jan 26, 2019)
Breaking

None.

Enhancements

Link to documentation pages from contents pages. John Fairhurst #730

Call out unavailable and deprecated Objective-C declarations. Stefan Kieleithner John Fairhurst #843

Bug Fixes

Support Swift 4.2 with --podspec. John Fairhurst #1015

Fix multiline copyright for apple theme. Fabien Lydoire John Fairhurst #1016

Source code(tar.gz)
Source code(zip)
v0.9.4(Jan 26, 2019)
Breaking

None.

Enhancements

None.

Bug Fixes

Fix crash with pre-existing Docs directory. John Fairhurst #965

Fix crash with unicode scalars in string literals. John Fairhurst #972

Fix error compiling a Swift podspec in Xcode 10. Minh Nguyễn #970

Source code(tar.gz)
Source code(zip)
v0.9.3(May 6, 2018)
Breaking

None.

Enhancements

None.

Bug Fixes

Fix crash when specifying empty Swift version. Now correctly uses the default Swift version.
JP Simard

Fix jony theme selection.
John Fairhurst #962

Source code(tar.gz)
Source code(zip)
v0.9.2(Apr 21, 2018)
Breaking

None.

Enhancements

Add a new 'jony' theme similar to the 2017 Apple documentation style.
Harshil Shah

Add the ability to limit documentation to certain files by passing in an -i/--include argument.
Nick Fox #949

Improve Swift declarations to look more like the Xcode Quick Help version, for example including { get set }, and include all attributes.
John Fairhurst #768 #591

Bug Fixes

Preserve MARK comment headings associated with extensions and enum cases.
John Fairhurst

Fix issue where Overview items were invalidly being referenced with NULL types in the generated Dash docset index.
Andrew De Ponte

Don't display FIXME or TODO comments as section markers.
John Fairhurst #658

Source code(tar.gz)
Source code(zip)
v0.9.1(Jan 8, 2018)
Breaking

None.

Enhancements

Added a config option (--undocumented-text UNDOCUMENTED_TEXT) to set the default text for undocumented symbols.
Akhil Batra #913

Added a config option to hide Objective-C or Swift declarations: --hide-declarations [objc|swift].
Ibrahim Ulukaya #828

Automatically use Swift or Objective-C syntax highlighting for code blocks in documentation comments. Improve Swift highlighting with latest Rouge.
John Fairhurst #218

Bug Fixes

Fix Swift declarations when generating Objective-C docs for generic types.
John Fairhurst #910

Don't create documentation nodes for generic type parameters.
John Fairhurst #878

Source code(tar.gz)
Source code(zip)
v0.9.0(Oct 27, 2017)
Breaking

Generate documentation coverage badge locally. Since this avoids the failable HTTP request to shields.io previously used to obtain the badge, we've removed the --[no-]download-badge flag and the corresponding download_badge YAML configuration key.
Samuel Giddins

Enhancements

None.

Bug Fixes

Fixed issue that prevented Jazzy from running on case sensitive file systems.
Jeremy David Giesbrecht #891

Fixed issue preventing --podspec from working with test_specs.
John Fairhurst #894

Always display correct declaration for undocumented symbols.
John Fairhurst #864

Trim common indentation in multiline declarations.
John Fairhurst #836

Source code(tar.gz)
Source code(zip)
v0.8.4(Sep 28, 2017)
Breaking

None.

Enhancements

Align jazzy terminology with Apple usage.
Xiaodi Wu John Fairhurst

Add url attribute that can be more accurate than {{section}}.html as a URL in custom templates.
John Fairhurst

Bug Fixes

Fix crash when specifying swift_version as a floating point value in .jazzy.yaml rather than a string.
JP Simard #860

Autolink from parameter documentation and from external markdown documents including README. Autolink to symbols containing & < >.
John Fairhurst #715 #789 #805

Fix Swift 4 declarations containing ampersands (&) being truncated.
JP Simard

Source code(tar.gz)
Source code(zip)
v0.8.3(Jul 7, 2017)
Breaking

None.

Enhancements

Generate Swift declaration for more Objective-C declarations.
Zheng Li

Improve quality & accuracy of Swift interfaces for Objective-C declarations when generating Objective-C docs.
Norio Nomura

Process Swift 3.2/4 doc comments.
John Fairhurst

Bug Fixes

Fix missing doc comments on some extensions.
John Fairhurst #454

Fix failure when attempting to download documentation coverage badge with jazzy using macOS system Ruby, or a Ruby built with outdated versions of OpenSSL.
JP Simard #824

Stop --skip-undocumented from skipping documented items nested inside extensions of types from other modules.
John Fairhurst #502

Fix members added to extensions of a nested type showing up in the parent.
John Fairhurst #333

Source code(tar.gz)
Source code(zip)
v0.8.2(May 13, 2017)
Breaking

None.

Enhancements

Report number of included and skipped declarations in CLI output.
John Fairhurst #238

Build ObjC docs with clang modules enabled by default (-fmodules flag).
Maksym Grebenets #636

Shave ~1MB from jazzy's gem distribution.
JP Simard

Bug Fixes

Fix support for Ruby 2.2.
John Fairhurst #801

Fix many cases of incorrect, missing or superfluous docs on Swift declarations.
John Fairhurst

Source code(tar.gz)
Source code(zip)
v0.8.1(May 2, 2017)
Breaking

None.

Enhancements

Allow all markdown in returns and parameter description callouts.
John Fairhurst #476

Bug Fixes

Fix a crash that occurred when a documentation comment ended with an extended grapheme cluster.
Lukas Stührk #794 SourceKitten#350

Source code(tar.gz)
Source code(zip)
v0.8.0(Apr 27, 2017)
Breaking

undocumented.json is now only in the output directory and is no longer copied into docsets.
Jeremy David Giesbrecht #754

Enhancements

Add --[no-]download-badge flag to skip downloading the documentation coverage badge from shields.io. Useful if generating docs offline.
JP Simard #765

Bug Fixes

Blank line no longer needed before lists or code blocks.
John Fairhurst #546

Linking to headers in apple theme gives correct vertical alignment.
John Fairhurst

Headers in source code markdown no longer cause corruption.
John Fairhurst #628

Source code(tar.gz)
Source code(zip)
v0.7.5(Mar 21, 2017)
A few important Ruby version fixes if you're using 2.0 or 2.4, as well as an old Objective-C bug if you were documenting a framework with nested headers.

Breaking

None.

Enhancements

None.

Bug Fixes

Fix issue where using a custom theme would crash jazzy when using Ruby 2.4.
Jason Wray #752

Fix support for Ruby 2.0.0.
Jason Wray #747

Fix issue where header files are not found if inside subdirectories of the framework_root specified folder.
Christopher Gretzki #518

Source code(tar.gz)
Source code(zip)