Jazzy, Jekyll, and Swift 2.1

I wanted to take a a moment and write out how I plan to document future Swift projectss.

Step One: Install

I found 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,

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

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.

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

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

Addendum

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

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.

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