Easy Documentation for your Swift project using Jazzy

Create a document for your swift project matching Apple’s official reference documentation without writing a single line of code outside Xcode.

Overview

In this blog we are going to learn about how to automatically generate documentation for your project written in Swift using Jazzy. The document can have:

• Detail description of the classes, functions, properties, structs, enums, protocols, extensions, and any other code structure or entity you have.
• Description of input (parameters) values and output (returns) values of your method.

Document is generated in bunch of linked HTML, CSS and JS files which looks exactly like the Apple documentation.

How to setup Jazzy ?

Open your Terminal from Dock and type following command:

sudo gem install jazzy

Enter your system password and wait till the process is completed.

If you get any kind of error during installation, make sure you have updated your ruby using following command: sudo gem update ruby. As Jazzy requires Ruby 2 or greater. Some users had issues with gem due to their macOS version. So if you’re one of them type this command in your terminal:

sudo gem install -n /usr/local/bin jazzy

The reason for failure of first command is because of some macOS features which restricts even administrators from writing to /usr/bin. After this installation , you’re ready to use Jazzy.

How to comment code in Xcode?

The code which you comment in Xcode will be used by Jazzy while creating document. Before starting, you should refer this Markdown Guide. This will be helpful for you to comment code as per guidelines. I am showing you an example.

This is a custom alert class in which I have commented the code like this.

Now when you call the following function you will find Apple like document in right panel of your Xcode. Just click on the function, you will see something like this.

How to Generate document ?

Navigate to project root folder using following command:

cd project_root_folder_path

For any help related to jazzy you can use:

jazzy --help

Now finally for creating document you can use:

jazzy --min-acl internal

You will get something like this.

Now, navigate to your Xcode project folder and you will see a folder ‘docs’. Open index.html from this folder and you will get your Apple like document site. The index.html for above generated project looks like this :

Thanks for your reading. I hope it would have help you.

For any queries and suggestions reach out at arpit.cor@gmail.com