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.
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
--documentationand provide additional, custom markdown docs. In PresenterKit, this is used to generate the Getting Started guide.
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:
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.