Generate & Host your iOS Documentation
Give your docs an upgrade
As a programmer, everyone tells you to be responsible and document your code. It gives context to the code that you're writing and makes it simpler to understand what’s going on.
Documenting our code is great, but what if we can generate and host pretty docs straight from our code? With the right setup, we can even search through our documentation. Take a look at a sample documentation page below:
What’s the plan?
In this post we’re going to generate a website for our documentation with Jazzy. Then learn how to host it with Github Pages and finally ensure that it stays up to date with Travis CI.
If you are unfamiliar with CI or haven't setup Travis CI for your project, take a look at this blog for some insights: "How to automate CI for and iOS Project"
Generating Documentation
As fast as a developer can write documentation, is as fast as it becomes outdated. We need a way to generate our documentation so we can avoid having to update our docs in many places.
Jazzy is a command line application that can generate Swift and Objective-C documentation into an html website.
Jazzy Installation
Before installing Jazzy, we need to install the “Xcode command line tools”. You can run the following command to install them: xcode-select —-install. Once installed, you can run the [sudo] gem install jazzy to install Jazzy.
After a successful installation, we can run Jazzy and customize it with different documentation options.
jazzy \
--min-acl internal \
--no-hide-documentation-coverage \
--theme fullwidth \
--output ./docs \
--documentation=./*.md1. min-acl internal
The min-acl attribute, controls the lowest access level that’s generated. Since we’re documenting all public functions and variables, we set it to internal. Private and Fileprivate functions and variables will not be in the generated docs. To document everything, the min-acl will need to be set to private.
2. no-hide-documentation-coverage
Enables the documentation percentage counter in the docs.
3. theme fullwidth
Changes to a custom theme with a search bar.
4. output ./docs
The output path of the generated documentation. Setting to ./docs will place all the generated files in a docs folder in the root of the project.
5. documentation = ./*md
Adds a section in the generated docs with a link to the ReadMe. We can use this as a home page for the docs.
Creating a Makefile to make life easier
Instead of writing the Jazzy command every time, we can encapsulate it inside of a “Makefile”.
documentation:
@jazzy \
--min-acl internal \
--no-hide-documentation-coverage \
--theme fullwidth \
--output ./docs \
--documentation=./*.md
@rm -rf ./buildBy using your favorite text editor of choice, you can create a new file and name it “Makefile”. After it’s created you can copy and paste the code above to define a new “documentation” command. Now from the terminal, we can generate our documentation by running make documentation.
Viewing the Generated Docs
Running Jazzy with the configuration above will create a docs folder in the root of the project. Inside this folder will contain the necessary HTML resources to view your docs.
Double clicking the index.html file will open a local instance of the generated docs on your default browser.
Hosting our shiny new docs
Now that we’ve generated our docs, the next step is to be able to host them for all to see. Code that’s stored on GitHub can take advantage of the nifty service called GitHub Pages. Developers can host a website on Pages to be able to share information about their project. In our case, we’re going to use it to host our generated documentation.
1. Create a “gh-pages” branch
Let’s create a new branch called gh-pages to be the dedicated branch that will hold our generated docs. We use a dedicated branch to prevent git from showing the generated HTML changes.
2. Update GitHub Settings
From your project’s settings on GitHub, scroll down to GitHub Pages. There’s an option to select the source for GitHub Pages. We’re going to select the gh-pages branch we created.
The GitHub Pages url is also displayed in this section, and will be different for each project. For the example project the url is: https://jgsamudio.github.io/TravisCIBlog/
3. Sync our Docs with Travis CI
Next, we want to use Travis CI to keep the gh-pages branch up to date whenever we make changes to our code. Update the .travis.yml file to the one below to allow Travis CI to update the gh-pages branch.
Compared to a standard .travis.yml file, we’ve added 2 new sections, after_success and deploy.
after_success
Travis CI will call the after_success section once it finishes all integration checks. Here, we can call a command to update our documentation. First, we install Jazzy by calling gem install Jazzy. Then we can update our documentation by calling the Makefile command, make documentation.
deploy
1. provider: pages
Travis CI can deploy our static documentation files we created with Jazzy to GitHub Pages.
2. skip-cleanup: true
To commit the new documentation changes we need to enable skip-cleanup. Enabling it will ensure the changes are not deleted once the build finishes.
3. github-token: $GH_TOKEN
To give Travis CI access to update our gh-pages branch, we need to give it access via a “Personal Access Token”. We will go over how to create an access token in the next section.
4. local-dir: docs
We specify where the static documentation is by using the local-dir attribute.
5. branch: master
We deploy our documentation to GitHub Pages whenever we merge new code into master.
More information on how to setup the .travis.yml file for GitHub Pages can be found in the link below.
Generating a Personal Access Token
To generate your own “Personal Access Token”, first go to your GitHub settings page. Then, select “Developer settings” and next “Personal Access Tokens” to view your tokens.
Select “Generate new token” and give it access to public _repo. This will give Travis CI access to public repositories when it’s time to deploy.
After generating the token, you will need to copy the token to Travis CI. Please note that if you refresh the page, you will no longer be able to copy the token. If this happens you can create a new one and delete the old one.
Next, navigate to your Travis CI project’s setting page and scroll down to “Environment Variables”. Here you can enter custom environment variables that will be available to use during each CI build. We named the token “GH_TOKEN” and pasted the token that was generated from GitHub.
Now with the updated .travis.yml file and “Personal Access Token”, we’re able to add new code into our repository. Documentation changes will now appear on GitHub Pages when they’re merged into the master branch.
Let’s add some documentation!
As a general rule, I tend to document all public functions and variables. It’s useful for other developers if they decide to use them from outside classes. Understanding what a piece of code does, and how to use it is critical to ensure there are no unexpected bugs.
For the example above, we’ve documented the enum cases, variables and functions. We also added documentation at the class level with a little code snippet. By adding the triple ```, the code snippet will show up in the generated documentation. “Warnings” and “notes” can also be specified with the -Warning: and the -Note: identifiers respectively.
Add a link to the ReadMe
Now that we’ve generated & hosted our documentation, we need a quick way to access it. Adding a link to it from the ReadMe would be a great way to quickly access them.
Thanks for reading! 🙌
If you have any questions, comments or requests for future articles please leave a comment below!
