I wanted to take a a moment and write out how I plan to document future Swift projects.
Step One: Install
I found Jazzy. It’s a command line utility for documenting Xcode projects. 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 project, and run
jazzy. You should get something like the following,
One super important note here. By default Jazzy only documents public methods. Therefore, you must pass Jazzy the flag
This is the only way you will get everything. If not, you will end up with an empty project, 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 project 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 project’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,
Here’s an example: behavioralBluetooth Docs
Step Four: Document your project
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.
Apparently excluding files from the documentation process is a little tricky.
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.