Swift documentation, Part 2

I previously wrote about writing great documentation in Swift. If you haven’t read that post, head there now to catch up. This post is a follow-up with updates for GitHub’s new way to publish docs. This is how I’ve setup all of my Swift open source projects.

Generating docs

As I mentioned before, you’ll want to use Realm’s jazzy — Soulful docs for Swift and Objective-C. Here’s an example of the docs script that I use for PresenterKit:

jazzy \
    --clean \
    --author 'Jesse Squires' \
    --author_url 'https://twitter.com/jesse_squires' \
    --github_url 'https://github.com/jessesquires/PresenterKit' \
    --module 'PresenterKit' \
    --source-directory . \
    --readme 'README.md' \
    --documentation 'Guides/*.md' \
    --output docs/ \

You need to tell jazzy where your source code is and provide some basic author information. It couldn’t be easier. Run jazzy --help to see all of the possible usage options.

New! With the latest version of jazzy, you can pass --documentation and provide additional, custom markdown docs. In PresenterKit, this is used to generate the Getting Started guide.

Publishing docs

In the previous post, publishing docs with GitHub was a somewhat clunky process where you had to create an orphan branch named gh-pages. Now, all you need to do is put your documentation in a top-level docs/ directory on your master branch. Notice the output directory in the jazzy script above: --output docs/.

Complete workflow

Once you’ve made changes to your code and header docs, run your script to generate the documentation which should dump everything into docs/. Then simply commit your changes and push to GitHub, where your documentation will be rendered automatically.