Publishing to GitHub Pages

GitHub is a company that offers Git hosting as a service. They also offer a static website-hosting service. Hosting a static website is often the only thing you need to publish your documentation online. One of the great features of GitHub is that we can publish documentation in the same repository as our code.

Configuring GitHub Pages is straightforward, as it sits right in the general settings of your repository.

GitHub offers multiple options for publishing your documentation to a static website:

The gh-pages option does not appear if you do not have a gh-pages branch.

As you will likely use the master branch for your codebase, you are left with two options: using the docs folder or the gh-pages branch. Each has its own advantages and drawbacks, but no one solution is better than the other in all scenarios.

The best is to try to find the solution that works for you.

If you select the docs folder solution, use the --output docs option with Jazzy, commit your changes and added files, and push.

Using the gh-pages branch is a bit trickier and will probably require some force-pushing:

# Clone the gh-pages branch in to the docs folder
git clone -b gh-pages --single-branch $REPO ./docs 

# Pull the latest changes
cd docs
git pull origin gh-pages 

# go back to the root folder
cd ..

# Generate the docs
jazzy –output docs_tmp

# Copy the docs in to the docs folder
cp -R docs_tmp/* "docs/”
cd docs
git add -A

# Commit your changes
git commit -am “Updates documentations…”

# push the changes to the gh-pages branch
git push

As you can see, the gh-pages solution involves more work, but in the long run, your code base is not polluted by artifacts that can be generated (or regenerated) by any commit.

Jazzy does not support API versioning, so if you want to publish versioned APIs you are out of luck.

In this first section, you have learned how to format the comments above your code properly in order to generate valid documentation for Xcode’s internal Quick Help as well as for Jazzy, the powerful documentation generator. You have also seen that GitHub can be used to publish your documentation alongside your code.

Documentation generation is something that should be automated, first because we don’t want contributors to bother with it, but mostly because machines are great at doing things over and over again.

In the next section, we will investigate how it is possible to use Travis or Circle, two continuous integration services, to run tests automatically, report the status of the tests, and ultimately ensure you, and your contributors, never introduce any bad commits!