Auto Doc

With Appledoc + Jenkins it is fabulously easy to have your documentation be automatically generated and uploaded to a documentation site. Let me give you a quick guided tour about the individual parts of our setup. The final result you can admire on our new Cocoanetics Documentation Site.

The first step of the process is to start adding Appledoc-style comments to your source code. Personally I only do this for the headers. The advantage there is also that you make your headers more clean if only for the fact that less methods in there need less documentation.

Add Appledoc

Since AppleDoc emits Xcode-compatible log statements you can add it as a target. This way you can “build” the documentation and the error messages are showing you directly in your code where documentation comments are incomplete.

In my original article on how to get started with Appledoc I advocated a lengthy build script to be added as a script step to a aggregate build target. I have since learned that you can also put the individual command line parameters into a property list. This reduces the necessary build parameters dramatically.

I changed the output to go into the build directory instead of the external help folder I was using before. Also it is nice to see the actually used settings, hence the –print-settings.

The contents of the AppledocSettings.plist have another advantage over command line parameters since they are structured by the plist.

This is the plist for the DTCoreText project, it took me some time and tweaking to get the settings just right. The output of this is a docket for use within Xcode plus it keeps the interim HTML files since those are the ones we want to upload to our web server too. I’m also adding some companion guide documents via the –include parameter. Those are markdown templates that get converted into HTML and put in the docs subfolder.

You know that you have everything set up correctly if you can execute /usr/local/bin/appledoc in your project root without any other parameters and it successfully builds the output.

Continuous Documentation Integration

We have a Jenkins Continuous Integration (CI) server. This has the ability to poll the repository for changes and kick off a build of our documentation whenever there is a change.

This is how the setup of the project looks like. Since this build requires an installed copy of the appledoc command line utility, I am restricting it to only run on the “Miraculix” build node. It specifically checks the master branch of the DTCoreText GitHub repo which it polls every 5 minutes.

In the second half of the settings you see the single build command which is quite similar to how we wired up in-Xcode-building. The final step is to send the build artifacts to the documentation server. Since we want to have both the HTML as well as the docset end up in the same folder I configured two transfer sets, both with the same remote directory target.

The result of this is one sub-folder per project on the doc site. Each documentation is self-contained and has an index page. People can browse the individual pages or subscribe to the atom feed to get updates fed directly into Xcode.

Automatic Index

Simon from Chester Solutions Ltd built an index.php page for us that converts the folder index into a nice web page. He took our website template CSS, deleted a few HTML nodes (like menu, search bar, social buttons) and scripted the logic to find the folders and their last modified dates for display.

Yes I know that it looks very basic, but I love that this does not require any manual work. We’re considering adding some Icons automatically, maybe we can use the ones that I have in the Demo apps that are part of the projects. Or maybe I can get some graphic artist to design something.

Conclusion

Before aggregating all documentation on our documentation site, I was using GitHub pages, aka the gh-pages branch of each project. The unfortunate side effect of this however is that each docset is a binary package and thus there is no way for GitHub to compress it. Each new documentation version would increase the repository size by half a megabyte.

Because of this we moved to a simple web server with FTP access and were able to remove the GitHub pages. There really is no sense in versioning the output of the documentation build process every step of the way.

If you make it a habit of properly adding documentation comments to your headers and you have a continuous integration server then it is no problem having the documentation also be automatically built and uploaded to a documentation site.

Categories: Recipes