Generating and publishing project docs with Travis CI

• It's nice when a project has autogenerated documentation,
• it's even nicer when this documentation is kept up to date,
• it's awesome when it is published automatically,
• and it's unbelievably cool when it is there for all branches!

This repository demonstrates how to do it.

The original idea was taken from here: https://gist.github.com/vidavidorra/548ffbcdae99d752da02. The approach was generalized, the script cleaned up and optimized.

The idea

We want our generated docs to be accessible under:

https://<our-username>.github.io/<our-project>/master/
https://<our-username>.github.io/<our-project>/branch-1/
https://<our-username>.github.io/<our-project>/branch-2/
...

It should be automatically generated and re-generated every time when the code is pushed to any branch. GitHub feature to make this publishing possible is called GitHub Pages, and the automation tool that we will use is Travis CI.

Example: https://dryewo.github.io/travis-docs-gen/master/

Steps

This example project does not really have real documentation generation, instead we just copy and rename index.tmpl file. In a real-world project one can insert a call to doxygen or any other documentation generation tool.

The following steps describe how to set this process for your own project, while this current repo can be used as a reference.

1. Enable your project on Travis CI

Get an account at Travis CI. Turn on Travis for your repository, using the control panel.

2. Create a clean gh-pages branch

Make sure you have no uncommitted changes before doing this:

cd /your/project/dir
git checkout --orphan gh-pages
git rm -rf .
echo "My gh-pages branch" > README.md
git add .
git commit -am "Clean gh-pages branch"
git push origin gh-pages

3. Create a gendoc.sh script

Create this file and make it executable (the name does not matter, but we will use gendoc.sh just for clarity):

touch gendoc.sh
chmod +x gendoc.sh

Put the contents of this repo's file, and replace the "Build" the documentation section with your project specific stuff. Keep in mind that all the generated files should be copied into $DOCS_DIR.

4. Create the .travis.yml file

Here we will need to enable Travis CI to push code to our repo. In order to do this, we will need to generate a Personal access token, encrypt it and include in .travis.yml.

First, copy settings from this repo's .travis.yml to yours. The important parts are:

branches:
  except:
  - gh-pages

and

after_success:
  - ./gendoc.sh

Then, generate a token:

0. In GitHub, go to settings and Personal access tokens;
1. Click Generate a new token and fill in the description. E.g. Travis CI Docs;
2. As scope select public_repo;
3. Click Generate token;
4. Copy the generated token.

WARNING This token will allow its user to push to any public repo that you have access to. Be careful and don't leak it. In case the token gets compromised, revoke it and generate a new one.

To avoid leaking, we will encrypt it, so that it can only be decrypted by Travis CI and only in the context of this project's builds:

0. Install the Travis CI client;
1. Run the following command: travis encrypt GH_TOKEN=<copied_personal_acces_github_token>;
2. This will give a very long line like secure: <encrypted_token>
3. Copy this line and add it to the environment variables in the .travis.yml.

5. Commit and push the code

If you did everything right, Travis CI build will be triggered after the push, and as a result of the build a new commit will appear under gh-pages branch of your repo. It will include a new dir master that will contain the results of generating the docs.

When someone makes a pull request, there will be two builds triggered (for the branch push and for the PR itself) and PR's corresponding branch name will be used to create a new dir in the gh-pages branch.

After that, the documentation will be available under

https://<your-username>.github.io/<your-project>/<branch>/

Happy hacking!