With the right setup, we can even search through our documentation.
Take a look at a sample documentation page below:BackgroundColorState Enumeration ReferenceThe state can be updated by overriding the state with the next background state.
jgsamudio.
github.
ioWhat’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 DocumentationAs 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 InstallationBefore 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 internalThe 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-coverageEnables the documentation percentage counter in the docs.
3.
theme fullwidthChanges to a custom theme with a search bar.
4.
output .
/docsThe 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 = .
/*mdAdds 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 easierInstead 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 DocsRunning 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.
Documentation DirectoryDouble clicking the index.
html file will open a local instance of the generated docs on your default browser.
Hosting our shiny new docsNow 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” branchLet’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 SettingsFrom 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/GitHub Pages Settings3.
Sync our Docs with Travis CINext, 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_successTravis 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.
deploy1.
provider: pagesTravis CI can deploy our static documentation files we created with Jazzy to GitHub Pages.
2.
skip-cleanup: trueTo 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_TOKENTo 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: docsWe specify where the static documentation is by using the local-dir attribute.
5.
branch: masterWe 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.
GitHub Pages Deployment – Travis CIDeploying to GitHub Pages uses git push –force to overwrite the history on the target branch, so make sure you only…docs.
travis-ci.
comGenerating a Personal Access TokenTo 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.
Creating a new “Personal Access Token”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.
Sample “Personal Access Token”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.
Travis CI Project SettingsNow 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 ReadMeNow 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!.. More details