Auto-deploying Doxygen documentation to gh-pages with Travis CI

This explains how to setup for GitHub projects which automatically generates Doxygen code documentation and publishes the documentation to the gh-pages branch using Travis CI. This way only the source files need to be pushed to GitHub and the gh-pages branch is automatically updated with the generated Doxygen documentation.

Sign up for Travis CI and add your project

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

Create a clean `gh-pages` branch

To create a clean gh-pages branch, with no commit history, from the master branch enter the code below in the Git Shell. This will create a gh-pages branch with one file, the README.md in it. It doesn't really matter what file is uploaded in it since it will be overwritten when the automatically generated documentation is published to the gh-pages branch.

cd /path/to/repository
git checkout --orphan gh-pages
git rm -rf .
echo "My gh-pages branch" > README.md
git add .
git commit -a -m "Clean gh-pages branch"
git push origin gh-pages

Create a generate documentation and deploy script

This script will generate the Doxygen documentation using the DOXYFILE for configuration and publish it to the gh-pages branch. Below is an example script that I use. This script will create a file called doxygen.log in the root of the gh-pages branch, containing the output of Doxygen. Besides the log it, of course, also generates the documentation itself. It is importand that the Doxygen configuration file has the OUTPUT_DIRECTORY set to empty and the INPUT starting with $(TRAVIS_BUILD_DIR). This way the script will know where the output of Doxygen is going to be located and can find the input files.

Script name: generateDocumentationAndDeploy.sh Script location: root of the repository

#!/bin/sh
################################################################################
# Title         : generateDocumentationAndDeploy.sh
# Date created  : 2016/02/22
# Notes         :
__AUTHOR__="Jeroen de Bruijn"
# Preconditions:
# - Packages doxygen doxygen-doc doxygen-latex doxygen-gui graphviz
#   must be installed.
# - Doxygen configuration file must have the destination directory empty and
#   source code directory with a $(TRAVIS_BUILD_DIR) prefix.
# - An gh-pages branch should already exist. See below for mor info on hoe to
#   create a gh-pages branch.
#
# Required global variables:
# - TRAVIS_BUILD_NUMBER : The number of the current build.
# - TRAVIS_COMMIT       : The commit that the current build is testing.
# - DOXYFILE            : The Doxygen configuration file.
# - GH_REPO_NAME        : The name of the repository.
# - GH_REPO_REF         : The GitHub reference to the repository.
# - GH_REPO_TOKEN       : Secure token to the github repository.
#
# For information on how to encrypt variables for Travis CI please go to
# https://docs.travis-ci.com/user/environment-variables/#Encrypted-Variables
# or https://gist.github.com/vidavidorra/7ed6166a46c537d3cbd2
# For information on how to create a clean gh-pages branch from the master
# branch, please go to https://gist.github.com/vidavidorra/846a2fc7dd51f4fe56a0
#
# This script will generate Doxygen documentation and push the documentation to
# the gh-pages branch of a repository specified by GH_REPO_REF.
# Before this script is used there should already be a gh-pages branch in the
# repository.
# 
################################################################################

################################################################################
##### Setup this script and get the current gh-pages branch.               #####
echo 'Setting up the script...'
# Exit with nonzero exit code if anything fails
set -e

# Create a clean working directory for this script.
mkdir code_docs
cd code_docs

# Get the current gh-pages branch
git clone -b gh-pages https://git@$GH_REPO_REF
cd $GH_REPO_NAME

##### Configure git.
# Set the push default to simple i.e. push only the current branch.
git config --global push.default simple
# Pretend to be an user called Travis CI.
git config user.name "Travis CI"
git config user.email "[email protected]"

# Remove everything currently in the gh-pages branch.
# GitHub is smart enough to know which files have changed and which files have
# stayed the same and will only update the changed files. So the gh-pages branch
# can be safely cleaned, and it is sure that everything pushed later is the new
# documentation.
rm -rf *

# Need to create a .nojekyll file to allow filenames starting with an underscore
# to be seen on the gh-pages site. Therefore creating an empty .nojekyll file.
# Presumably this is only needed when the SHORT_NAMES option in Doxygen is set
# to NO, which it is by default. So creating the file just in case.
echo "" > .nojekyll

################################################################################
##### Generate the Doxygen code documentation and log the output.          #####
echo 'Generating Doxygen code documentation...'
# Redirect both stderr and stdout to the log file AND the console.
doxygen $DOXYFILE 2>&1 | tee doxygen.log

################################################################################
##### Upload the documentation to the gh-pages branch of the repository.   #####
# Only upload if Doxygen successfully created the documentation.
# Check this by verifying that the html directory and the file html/index.html
# both exist. This is a good indication that Doxygen did it's work.
if [ -d "html" ] && [ -f "html/index.html" ]; then

    echo 'Uploading documentation to the gh-pages branch...'
    # Add everything in this directory (the Doxygen code documentation) to the
    # gh-pages branch.
    # GitHub is smart enough to know which files have changed and which files have
    # stayed the same and will only update the changed files.
    git add --all

    # Commit the added files with a title and description containing the Travis CI
    # build number and the GitHub commit reference that issued this build.
    git commit -m "Deploy code docs to GitHub Pages Travis build: ${TRAVIS_BUILD_NUMBER}" -m "Commit: ${TRAVIS_COMMIT}"

    # Force push to the remote gh-pages branch.
    # The ouput is redirected to /dev/null to hide any sensitive credential data
    # that might otherwise be exposed.
    git push --force "https://${GH_REPO_TOKEN}@${GH_REPO_REF}" > /dev/null 2>&1
else
    echo '' >&2
    echo 'Warning: No documentation (html) files have been found!' >&2
    echo 'Warning: Not going to push the documentation to GitHub!' >&2
    exit 1
fi

Create the Travis CI file

This script will handle the build and call the previous created generateDocumentationAndDeploy script.

Script name: .travis.yml Script location: root of the repository

# This will run on Travis' 'new' container-based infrastructure
sudo: false

# Blacklist
branches:
  except:
    - gh-pages

# Environment variables
env:
  global:
    - GH_REPO_NAME: <your_repo>
    - DOXYFILE: $TRAVIS_BUILD_DIR/<path_to_your_doxygen_configuration_file>
    - GH_REPO_REF: github.com/<your_name>/<your_repo>.git

# Install dependencies
addons:
  apt:
    packages:
      - doxygen
      - doxygen-doc
      - doxygen-latex
      - doxygen-gui
      - graphviz

# Build your code e.g. by calling make
script:
  - make

# Generate and deploy documentation
after_success:
  - cd $TRAVIS_BUILD_DIR
  - chmod +x generateDocumentationAndDeploy.sh
  - ./generateDocumentationAndDeploy.sh

Provide Travis CI with encrypted credentials for publishing to `gh-pages`

A tricy part of this setup is to provide Travis CI with the ability to deploy to gh-pages without making the required credentials public. The solution for this is to use a personal acces token for GitHub and use Travis' encryption support.

Generating a personal access token for GitHub

In GitHub, go to settings and Personal access tokens;
Click Generate a new token and fill in the description. E.g. <your_repo> Travis CI Documentation;
As scope select public_repo;
Click Generate token;
Copy the generated token.

Adding the secure variable to Travis CI

To add this personal access token to Travis CI there are two methods. In this example I've used the fist method, since it is the easiest one.

Method 1: Using the Repository Settings

Method 2: Using the Encrypted Variables

Follow the method described by the Travis CI documentation

Install the Travis CI client;
Run the following command travis encrypt GH_REPO_TOKEN=<copied_personal_acces_github_token>;
This will give a very long line like secure: <encrypted_token>
Copy this line and add it to the environment variables in the .travis.yml file as shown below.

env:
  global:
  - secure: <encrypted_token>

See it in action

I use this setup for one of my projects. The documentation of that project is hosted on the gh-pages branch.

The relevant files for this setup are:

Feel free to come with any suggestions for this setup!

4e1e0603/auto-deploy_documentation.md