Adding documentation to your project

Writing documentation for your project can be done right from the code files. This ensures there’s a strong connection between the actual code and the documentation, which will help you stay organized as your project grows.

Keeping docs in separate directories is suboptimal. Not only that, it will also encourage future contributors, including yourself, to update the documentation when you make changes to your code.

Swift uses a special flavor of Markdown. If you aren’t already familiar with that, check out the following guides:

In short, you should prepend a Markdown string with triple slashes ( /// ) to each public variable, function, and class, explaining what it does.

One thing the above articles don’t touch on is usage examples — the greatest way of documenting something. So let’s look at that now.

Like most Markdown parsers, you can add ### for a subheading, which you probably want to use to differentiate your usage example from the description. In contrast to some other parsers, Swift works better if you also add ### to the end of the line.

To write code blocks, I recommend you use 4 grave accents: ```` .

Here’s a representative usage example:

And here’s what it will look like on the documentation website:

Of course, multiple usage examples work, too:

Jazzy

Now that you’re an expert in writing documentation comments for your code, let’s look at how to generate pretty webpages.

Installation

The installation is beyond easy with the Ruby package manager:

sudo gem install jazzy

Generating docs

To generate documentation, simply run jazzy in the terminal (you should cd into your project’s directory).

jazzy

Jazzy parses all your files and generates a webpage for each object.

Customization

By default, these pages look pretty good, but you can also customize them to fit your specific needs. For example, let’s say you want to link to your own webpage. To do this, you can pass the --author_url parameter.

jazzy \ --author_url http://rickwierenga.com \

While this works perfectly fine when you run jazzy locally, it will get messy very quickly when you host the documentation generation process on GitHub. And it’s not easy to share the settings with other contributors.

So instead let’s write a .jazzy.yaml file that hosts your configuration. If you’ve never seen YAML before, don’t worry—it’s just like a Word document.

If we wanted to put the above configuration in a separate file, it would look something like this:

author_url: http://rickwierenga.com

Let’s add a few more properties:



author: Rick Wierenga

github_url:

theme: fullwidth author_url: http://rickwierenga.com author: Rick Wierengagithub_url: https://github.com/rickwierenga/ theme: fullwidth

Note theme ? Yes, Jazzy supports different themes!

To get a full list of configuration options, run:

jazzy --help config

Viewing your docs locally

Before pushing to GitHub, it’s always a good idea to validate that your code is working. In this case, that means checking if your documentation was generated correctly.

You can view the documentation in Safari by typing open docs/index.html in the terminal. If this does not open Safari but a text editor, for example, type open docs , which will open a Finder window. Then find index.html and drag in into Safari.

Note that you shouldn’t push the docs folder to GitHub because your documentation will be hosted on a separate branch. So a docs folder would only be confusing. Moreover, it will probably create a lot of unwanted merge conflicts. It’s better to add it to your .gitignore file.

Creating the main GitHub Pages

To host something on GitHub Pages, you need to create your own home page.

a) I already have a GitHub Pages page

If you already have a GitHub Pages page, that’s great! You can keep your homepage, and GitHub will automatically host your docs at example.github.io/your_package .

b) I don’t have a GitHub Pages page yet

If you do not have a GitHub Pages page, you can create one super easily by creating a new GitHub repository titled <your-username>.github.io . You should check “Initialize this repository with a README” on creation.

After a couple of minutes, you can visit <your-username>.github.io in your favorite browser to see your personal page.

For more information, check out the following links:

GitHub Actions

In order to run GitHub Actions, your library needs to be public. GitHub grants you free macOS compute in exchange for your efforts in contributing to open source ❤️

To run jazzy automatically, we’ll use a preconfigured GitHub Action called “Publish Jazzy Docs” available here:

Navigate to github.com/<your-username>/<your-package>/actions/new . In the top right corner, select “Set up a workflow yourself.”

This will open GitHub’s Actions editor. Again, this is a yaml file.

3. The following code would be a good start.

name: PublishDocumentation on:

release:

types: [published] jobs:

deploy_docs:

runs-on: macOS-latest

steps:

- uses: actions/checkout@v1

- name: Publish Jazzy Docs

uses: steven0351/publish-jazzy-docs@v1

with:

personal_access_token: ${{ secrets.ACCESS_TOKEN }}

config: .jazzy.yaml

This Action runs automatically if you create a new release. It also uses your .jazzy.yaml file to load the configuration.

You could change

on:

release:

types: [published]

to

on: [push]

to run regenerate documentation on every commit.

If you’re interested in learning more, check out the Action homepage:

4. In order to publish anything to GitHub Pages, a program needs a special access token. The reason for this is that the default GitHub Action access token provided to all Actions doesn’t have access to GitHub Pages. Your access token should have at least repo privileges. See the following document:

Remember the token, because you won’t be able to see it again.

5. To use this token, you’ll need to make it accessible to your workflows. You can do that by going to settings > secrets > new. Call it ACCESS_TOKEN .

6. Next, you should create a new gh-pages branch. To do this, select the master branch and type gh-pages . Click on the Create branch: gh-pages from 'master' link.

GitHub/jazzy will now run your workflow and build the documentation website.

For more information on GitHub Actions checkout the GitHub Action homepage:

Hosting the docs

As I mentioned earlier, GitHub offers to host your documentation for free through GitHub Pages. Setting this up is super easy.

Then navigate to https://github.com/<your username>/<your-package>/settings . Scroll down to “GitHub Pages.”

From “Source” select the “gh-pages branch” option.

The page will reload and show you the link to your docs page.

Congratulations 🎉 GitHub now hosts your project.

More GitHub Actions

Automatically publishing documentation is not the only thing you can do with GitHub Actions — many other awesome GitHub Actions exist. Here are some of my favorites:

Testing

You might also like this Action, which automatically runs tests on Ubuntu and/or macOS. Including tests for your PRs!

Styling

The swiftlint (another Realm project) GitHub Action to enforce a consistent code style:

What’s next?

There you go! You now have a perfect testing/documentation setup for your Swift Package.

Here are some useful links to explore:

The jazzy GitHub repo:

This tutorial on how to make design APIs in Swift by John Sundell: