A command-line utility that generates documentation for Swift or Objective-C

When you think of a command line utility, you usually think of a tool that just generates a bunch of stuff for you. Apple provides one with Xcode, but it can be overkill for most people. There are tons of great tools for just about every programming language, but how many of them are there to generate documentation for your project? Read on, as I introduce one that generates documentation for Swift or Objective-C.

If you’re an iOS developer, you know that the documentation for Swift and Objective-C is lacking. If you’re lucky enough to have an external API to a popular system, you may have a decent API reference, but most of us either have to write a few lines of documentation or resort to a screenful of ugly comments.

jazzy

jazzy is a command line tool to generate documentation for Swift or Objective-C. Swift and Objective-C projects are supported. Instead of parsing your source files, jazzy connects to Clang and SourceKit to use the AST representation of your code and its comments to get more accurate results. The result matches the look and feel of Apple’s official reference documentation released after WWDC 2014. Jazzy can also generate documentation from compiled Swift modules by using their symbolic graphs instead of the source code. This project adheres to the Code of Conduct of the Convention of Contributors. By participating in the event, you agree to abide by this code. Please report any unacceptable behavior to [email protected].

Requirements

You need development tools to create the project you want to document. Jazzy supports projects both in Xcode and in the Swift package manager. Jazzy expects it to work on macOS. Here are some tips for running Jazzy under Linux.

Setting

Use

Start jazzy from the command line. Run the jazzy -h command to get a list of additional options. If your swift module is built first and builds well, if jexcodebuild or swift build runs without arguments from the project root, then running jazzy (without arguments) from the project root should also work! If Jazzy generates documents for the wrong module, use –module to indicate which module you prefer. If that didn’t work and you’re using Xcode, try passing additional arguments to xcodebuild, for example. B. jazzy –build-tool-arguments -scheme,MyScheme,-target,MyTarget. You can define the parameters of your project documentation in the configuration file, default .jazzy.yaml. For a detailed explanation and a full list of all available options, run jazzy –help config.

Supported documentation keywords

Swift documentation is written in Markdown format and supports a number of special keywords. Here are some resources with tutorials and examples, starting with the most recent: The same keywords are supported for Objective-C documentation, but note that the format is slightly different. In Swift, we would write -returns:, but in Objective-C, we write @return. For more information, see the Apple HeaderDoc User’s Guide. Note: jazzy does not currently support all the Objective-C keywords mentioned in this document, only @param, @return, @warning, @see and @note. Jazzy can also cross-reference your documentation. A character name in backslash generates z. B. a link:

• MyClass – Link to the documentation of MyClass.
• MyClass.method(param1:)` – Reference to the documentation for this method.
• MyClass.method(…)` is an abbreviated syntax for the same thing.
• Method(…)` is an abbreviated syntax for referring to a method in the documentation of another method or property of the same class.
• MyClass method1]` is a reference to an Objective-C method.
• `-[MyClass method2:param1]` is a reference to another Objective-C method.

Jazzy also includes Apple’s DocC-style links, for example:

• MyClass/method(param1:)“ is a reference to the documentation for this method, which appears on the rendered page simply as method(param1:).
• “<doc:method(_:)-e873>` refers to a specific overload of method(_:). Jazzy doesn’t know which overload you have in mind, and refers to the first one.

Mathematics

Jazzy can display mathematical equations written in LaTeX, embedded in your Markdown :

• `$equation$` displays the equation in inline style.
• `$$equation$$ displays a display-style equation centered on its own line .

For example: Markdown : Online: `$ax^2+bx+c=0 Block: `$$x={frac {-bpm {sqrt {b^{2}-4ac}}}}{2a}}}}$`. …looks like this: The mathematical support is provided by KaTeX.

Swift

Swift documentation is created by default.

Example

This is how Realm Swift documents are created: 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.962 –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 documents are created for a project using the Swift package manager: jazzy –module DeckOfPlayingCards –swift-build-tool spm –build-tool-arguments -Xswiftc,-swift-version,-Xswiftc,5

Target-C

To create documentation for Objective-C headers, pass the following parameters to jazzy :

• –objc
• umbrella head…
• –Kader Root…
• –sdk [iphone|watch|appletv][os|simulator]|macosx (optional, default is from macosx)
• –hide-declarations [objc|swift] (optional, hides declarations for the selected language )

Example

This is how Realm Objective-C documents are created: 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 documentation came about: 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 . –Block AFNetworking

Mixed Objective-C / Swift

This feature is new and has some flaws. To create documentation for a mixed Swift and Objective-C project, you must first create two SourceKitten files: one for Swift and one for Objective-C. Then transfer these jazzy files with –sourcekitten-sourcefile.

Example

For example, the documentation is generated from an Xcode project for a module with Swift and Objective-C files: # generate Swift SourceKitten output sourcekitten doc — -workspace MyProject.xcworkspace -scheme MySchema > swiftDoc.json # Create Objective-C output SourceKitten sourcekitten doc –objc $(pwd)/MyProject/MyProject.h — -x objective-c -isysroot $(xcrun –show-sdk-path –sdk iphonesimulator) -I $(pwd) -fmodules > objcDoc.json # Pass both results as a comma-separated list to Jazzy jazzy –sourcekitten-sourcefile swiftDoc.json,objcDoc.json

Documents from .swift modules or frameworks

This feature is new and builds on the new Swift : Errors and omissions are possible: Messages are welcome. Swift 5.3 added support for generating character schemas from .swift module files. This seems to be part of Apple’s online document creation toolkit. Jazzy can use it to create API documentation. This method is faster than using the source code directly, but has its limitations: For example, comments in the documentation are only available for public statements, and the representation of -Swift extensions may not match the way they are written in the code. Some examples:

1. Create documentation for the Apple Combine framework for macOS:jazzy –module Combine –swift-build-tool symbolgraph

The SDK library directories are included in the default search path .

1. 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 triplet and must be compatible with the SDK. The default value is the target of the host system that Jazzy is running on, is something like x86_64-apple-darwin19.6.0.

1. documentation for the personal module .swiftmodule:jazzy –module MyMod –swift-build-tool symbolgraph –build-tool-arguments -I,/Build/Products create

This means that /Build/Products/MyMod.swiftmodule exists. By default, Jazzy looks for –source-directory (the current default directory), , so just substitute -I if that is not enough.

1. For the personal framework:jazzy –module MyMod –swift-build-tool symbolgraph –build-tool-arguments -F,/Build/Products

This means that /Build/Products/MyMod.framework exists and contains .swift module. Also here –source-directory, if the -F option is not passed, the default is to search in . See swift symbolgraph-extract –help for everything –build-tool-arguments : If your module has dependencies, you may need to add different search path options to get Swift to load the module.

Topics

Three themes are included with jazzy: apple (default), fullwidth and jony. You can specify the theme to be used by passing the –theme parameter. You can also provide with your own custom theme by specifying the path to the theme folder.

Guides

By default, jazzy looks for one of the files README.md, README.markdown, README.mdown, or README (in that order) in the folder from which it is started to create the index page in the root folder of the output documents. You can use the –documentation option to include additional formatting files in generated documents and in the navigation sidebar. Any files found that match the file template will be parsed and included in the Guide document type when it is created. If the files are not included with the custom_categories configuration option, they will be grouped under the Other Guides heading in the navigation sidebar. There are some limitations:

• File names must be unique to the source files.
• Readme must be specified separately with the readme option.

Section Description Summary

You can use the –abstract option to allow additional formatting after the header on pages with a section summary. Think of it as a model. The list of files that match the template is compared to the list of generated sections, and if a match is found, its contents are included in that section before the source code is released. Unlike the –documentation option, these files are not included in the navigation, and if the file does not match the section name, it is not included at all. This is very useful if you use custom_categories to group types and include the appropriate documentation in those sections. For an example of a project that uses both –documentation and –abstract, see: https://reswift.github.io/ReSwift/.

Check what is documented

In Swift mode, Jazzy documents only public and public statements by default. To enable statements 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 file it contains. You can use –exclude, –include, or :nodoc: to determine which statements are documented. In the documentation, the –include and –exclude flags list the source files to be included or excluded by . The items in the list can be absolute pathnames starting with /, or relative pathnames. Relative paths are interpreted relative to the directory from which you run jazzy or, if flags are defined in the configuration file, relative to the directory that contains the configuration file. The entries in the list may correspond to multiple files , where * stands for any number of characters, including /. For example:

• jazzy –include=/Users/fred/project/Sources/Secret.swift — contains a specific file
• jazzy –exclude=/*/Internal* — excludes all files whose names begin with Internal , and all files in any directory whose names begin with Internal.
• jazzy –exclude=Impl1/*,Impl2/* — exclude all files in the Impl1 and Impl2 directories from the current directory.

Note that the –include option is applied before the –exclude option. For example:

• –include=/*/Internal* –exclude=Impl1/*,Impl2/* –includes all files named that begin with Internal and all files in any directory whose name begins with Internal, except files in the Impl1 and Impl2 directories in the current directory

Statements whose documentation comment contains :nodoc: are excluded from the documentation.

Documentation structure

By default, Jazzy does not create separate web pages for statements that have no members: Instead, they are nested within the parent page. Use the –separate-global-declarations flag to change this and always create pages for declarations that are directly accessible to the client code.

Swift language version selection

Jazzy normally uses the Xcode Swift compiler, currently configured with xcode-select. Use the –swift-version option to compile with a different version of Xcode . The value you specify in –swift-version must be the Swift language version specified by the swift –version command in the Xcode you wish to use. For example, to use Xcode 9.4 : jazzy –swift-version 4.1.2

Linux

Jazzy uses SourceKitten to communicate with the environment and the Swift build compiler. The sourcekitten binary in the Jazzy gem is made for macOS and therefore does not work on other operating systems. To use Jazzy under Linux, you must first install and build SourceKitten by following the instructions in the SourceKitten repository on GitHub. To then create documentation for the SwiftPM project instead of just jazzy do : sourcekitten doc –spm > doc.json jazzy –sourcekitten-sourcefile doc.json We hope to be able to improve this process in the future.

Troubleshooting

Swift

Are the extensions only mentioned in the documentation? Check the –min-acl parameter – see above. Xcode with Swift version X not found

1. The value passed with –swift-version must exactly match the version number specified with swiftc –version. For example, Xcode 10.1 requires –swift-version 4.2.1. See the documentation on flags.
2. The Xcode you want to use must be in the Spotlight index. You can check with mdfind ‘kMDItemCFBundleIdentifier == com.apple.dt.Xcode’. Some users report that rebooting solves this problem; mdutil -E may also help. If none of these methods work, you can set the DEVELOPER_DIR environment variable to point to the desired Xcode before running Jazzy without the –swift-version flag.

Installation problems

Cannot find header/clang files Some of the Ruby gems that Jazzy depends on have built-in C extensions. This means that to build it you need to install the Xcode command line development tools: Run xcode-select –install to install the tools. /Applications/Xcode : Such a file or folder does not exist The active Xcode installation path must not contain any spaces. So /Applications/Xcode.app/ is fine, /Applications/Xcode-10.2.app/ is fine, , but /Applications/Xcode 10.2.app/ is not. This restriction only applies to when Jazzy is installed, not when it is run.

MacOS before 10.14.4

From version 0.10.0 of Jazzy, if you encounter a bug similar to the one in dyld : Symbol not found: _$s11SubSequenceSlTl, then you need to install Swift 5 runtime support for command line tools. You can do this too:

• Upgrade to macOS 10.14.4 or higher; or
• Install Xcode 10.2 or higher in /Applications/Xcode.app.

Development

Please refer to the Jazzy contribution guidelines when submitting correction requests. jazzy is in two parts:

1. Analyzer, SourceKitten (written in Swift)
2. Website generator (written in Ruby)

To make jazzy and run from the :

1. Install Bundler.
2. Start the bundle installation from the root of this archive.
3. Start jazzy from source by executing bin/jazzy.

Instructions for building SourceKitten from source can be found in the SourceKitten GitHub repository.

Design objectives

• Create source code documentation that matches the official Apple reference documentation.
• Support for standard syntax for documentation comments in Objective-C and Swift
• Use of modern tools for the creation of HTML templates (Mustache)
• Leverage the power and accuracy of Clang AST and SourceKit
• Dash Docsets Support
• Support for Swift and Objective-C

GitHub

https://github.com/realm/jazzy

Related Tags:

swift generate documentationjazzy swiftxcode documentation generatorjazzy markdownxcode export documentationjazzy yaml,People also search for,Privacy settings,How Search works,swift generate documentation,jazzy swift,xcode documentation generator,jazzy markdown,xcode export documentation,jazzy yaml,jazzy fastlane,xcods