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.
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
--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.