Jazzy and not Swift-DocC

There is one important case though in which you can not use Swift-DocC yet: For your own app's code. If you are not building a framework and instead want to generate some nice HTML docs for your app project, you can not use Swift-DocC at the moment. Sure, for many projects this would be overkill anyways. But in some industries, you just have to have documentation beyond the pure code due to legal or other process requirements, e.g. in the medical and finance industries. In this case, Jazzy can be the tool you are looking for.

Getting started on an M1 Mac

I am writing this under the assumption that you are running an M1 Mac, because that is the future. If you are still on Intel, no problem, you can actually leave out one step or follow the official docs. If you are on Apple Silicon such as an M1, there is one issue in the installation that you have to deal with.

Make sure you have gem installed

You will need the gem tool that is well known in the Ruby community.

My suggestion is to install it with homebrew, but any other way is fine too.

To check if you have gem installed already, open a terminal and run:

gem -v

It will either give you some meaningful version number or fail. Install gem in your favorite way in that case.

Install Jazzy

The first task is to install Jazzy itself.

Open a terminal and run:

sudo gem install jazzy

This should run without any issues on your Apple Silicon Mac with the default ruby version on your Mac.

I tried it with macOS 12.1 and the pre-installed ruby version, which was 2.6.8 in my case.

Install ffi to avoid a 'Bus Error'

When I first did this, I followed the docs. So I ran Jazzy right after the gem install and then I got a Bus Error. This seems to be a specific Apple Silicon issue at the moment. So before running Jazzy, do this on the terminal:

gem install --user-install ffi -- --enable-libffi-alloc 

Select the full Xcode app instead of the command line

Next up, you might run into an error like

xcode-select: error: tool 'xcodebuild' requires Xcode, but active developer directory '/Library/Developer/CommandLineTools' is a command line tools instance 

To fix it, run:

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer/ 

assuming that your Xcode path is the default one. Otherwise, adjust the path accordingly.

This will use the full-fledged Xcode tools instead of the simplified command line variant, which is necessary for Jazzy to run.

Jazzy needs a few parameters to run

The next trap I fell into was that Jazzy supposedly runs without parameters, which it does not typically.

If you run Jazzy for the first time and you get an error like

Could not successfully run xcodebuild

then chances are, that you need to specify more or different parameters on the command line.

This is how I got Jazzy to run correctly the first time:

cd yourAppDirectory # the one with the xcodeproj / xcworkspace in it

jazzy --clean --author "Raphael Haase" --author_url https://sylvilagus.com -x -workspace,DemoApp.xcworkspace,-scheme,DemoAppScheme

As you can see, I had to specify that we want Jazzy to use the xcworkspace. By default, it will only look at the pure Xcode project. So if you use Cocoapods, Jazzy running xcodebuild will not see the pods. You will typically see errors like:

no such module 'RxSwift'

when you forget to specify the workspace in the command line parameters.

So just specify your workspace file name and to be on the safe side the scheme name you want to use as well, particularly if you have more than one scheme in your app.

Include internal symbols



This one depends a bit on what you want to achieve. By default, Jazzy will only include the public symbols from your app. Sort of like you were developing a framework or as if we were still using Objective-C where there was only public, protected and private, but not internal.

So in my case, I wanted to see also the internal symbols from my app since I want to generate a somewhat comprehensive documentation of the app's code itself and have that in HTML and not just in the Swift code for said regulatory reasons.

Add --min-acl internal to the list of parameters on the command line when running Jazzy to achieve this.

So overall, I used this command to run Jazzy:

cd yourAppDirectory

jazzy --clean --author "Raphael Haase" --author_url https://sylvilagus.com -x -workspace,DemoApp.xcworkspace,-scheme,DemoAppScheme --min-acl internal

Et voilà, now I have some nice HTML docs to start with.