Jazzy, Jekyll, and Swift 2.1
Tags: robots, swift, jazzy
Published: 2016-01-18 10:00:00

---
title: Jazzy, Jekyll, and Swift 2.1
published: true
tags: robots, swift, jazzy
published_at: 20160118T10:00Z
series: None
canonical_url: https://ladvien.com/jazzy
main_image: https://ladvien.com/images/jazzy.jpg
---
I wanted to take a a moment and write out how I plan to document future Swift projectss.

### Step One: Install
I found [Jazzy](https://github.com/Realm/jazzy).  It's a command line utility for documenting Xcode projectss.  Nifty thing is, it is one of the few which works with Swift 2+. Anyway, it is pretty painless to get up and going.

The one catch I found was Swift is changing versions often, so you may have to wait a bit for the developers to catch up.  However, when the updates are released it is pretty easy to get things working again, simply run, `sudo gem update` in the terminal.

### Step Two: Running
To run Jazzy you simply open a terminal window on your Mac, navigate to the top folder of your Xcode projects, and run `jazzy`.  You should get something like the following,

```xml

Running xcodebuild
Parsing ViewController.swift (1/3)
Parsing bleTableViewController.swift (2/3)
Parsing AppDelegate.swift (3/3)
building site
jam out ♪♫ to your fresh new docs in `docs`

```

One super important note here.  By default Jazzy _only_ documents public methods.  Therefore, you _must_ pass Jazzy the flag

```xml

jazzy --min-acl internal private

```

This is the only way you will get everything.  If not, you will end up with an empty projects, most likely.  Had to find this out the hard way.  [Reference to the solution](https://github.com/realm/jazzy/issues/255).

If jazzy parsed everything correctly you will have a `docs` folder in your projects folder.  This docs folder is a pseudo-website build.  

### Step Three: Push to Pages
To get your documentation online, copy the `docs` folder to your an appropriate directory in your Jekyll site map.  Commit and push.  Now your projects's documentation is apparent of the global singleton known as human knowledge.  To get a link to the index of your documentation add the following,

`[Test](director_you_chose_to_put_docs_folder/docs/index.html)`

Here's an example: [behavioralBluetooth Docs](/jazzy/behavioralBluetooth/index.html)

### Step Four: Document your projects

I wont rehash Jazzy instructions.  In short, you can put Markdown in your comments within the code and the parser will pick up the comments and associate them with the methods etc they are close.

[Jazzy Instructions](http://ericasadun.com/2015/06/14/swift-header-documentation-in-xcode-7/)

### Addendum
Apparently excluding files from the documentation process is a little tricky.

```xml

jazzy  --exclude /Users/Ladvien/Desktop/behavioralBluetooth/behavioralBluetooth/AppDelegate.swift,/Users/Ladvien/Desktop/behavioralBluetooth/deviceState.swift
```

It should look like above, "--exclude" (not the double dash) followed by the _absolute_ path of the file to be excluded.  Then a comma (","), no space, and then the absolute path of the second file you wish to exclude.  It's pretty easy to make this into a script by doing the following.

```xml

1. From the terminal type: nano my_jazzy_script
2. Paste the finished command, such as the one listed above.
3. "Write-Out" the changes.
4. Exit nano.
5. At the terminal type: chmod +x my_jazzy_script (this makes the file executable).
6. To run the script type: ./my_jazzy_script

```