1#!/bin/bash 2################################################################################ 3# Notes : 4# Preconditions: 5# - Packages doxygen doxygen-doc doxygen-latex doxygen-gui graphviz 6# must be installed. 7# - Doxygen configuration file must have the destination directory empty and 8# source code directory. 9# - A gh-pages branch should already exist. 10# 11# Required global variables: 12# - DOXYFILE : The Doxygen configuration file. 13# - GH_REPO_NAME : The name of the repository. 14# - GH_REPO_REF : The GitHub reference to the repository. 15# - GH_REPO_TOKEN : The GitHub application token. 16# 17# This script will generate Doxygen documentation and push the documentation to 18# the gh-pages branch of a repository specified by GH_REPO_REF. 19# Before this script is used there should already be a gh-pages branch in the 20# repository. 21# 22################################################################################ 23 24################################################################################ 25##### Setup this script and get the current gh-pages branch. ##### 26echo 'Setting up the script...' 27# Exit with nonzero exit code if anything fails 28set -e 29 30GH_REPO_NAME= 31GH_REPO_REF= 32GH_REPO_TOKEN= 33 34usage() { echo "Usage: `basename $0` options (-n value) (-r value) (-t value)" 1>&2; exit 1; } 35 36if ( ! getopts ":n:r:t:" opt); then 37 usage 38fi 39 40while getopts :n:r:t: opt; do 41 case $opt in 42 n) 43 GH_REPO_NAME=$OPTARG 44 ;; 45 r) 46 GH_REPO_REF=$OPTARG 47 ;; 48 t) 49 GH_REPO_TOKEN=$OPTARG 50 ;; 51 *) 52 usage 53 ;; 54 esac 55done 56 57shift $((OPTIND - 1)) 58 59[ -n "$GH_REPO_NAME" ] || { 60 echo "ERROR: -n GH_REPO_NAME is not defined" >/dev/stderr 61 exit 1 62} 63 64[ -n "$GH_REPO_REF" ] || { 65 echo "ERROR: -r GH_REPO_REF is not defined" >/dev/stderr 66 exit 1 67} 68 69[ -n "$GH_REPO_TOKEN" ] || { 70 echo "ERROR: -t GH_REPO_TOKEN is not defined" >/dev/stderr 71 exit 1 72} 73 74################################################################################ 75##### Upload the documentation to the gh-pages branch of the repository. ##### 76# Only upload if Doxygen successfully created the documentation. 77# Check this by verifying that the html directory and the file html/index.html 78# both exist. This is a good indication that Doxygen did it's work. 79if [ -d "html-out" ] && [ -f "html-out/index.html" ]; then 80 81 # Create a clean working directory for this script. 82 mkdir code_docs 83 cd code_docs 84 85 # Get the current gh-pages branch 86 git clone -b gh-pages https://git@$GH_REPO_REF 87 cd $GH_REPO_NAME 88 89 ##### Configure git. 90 # Set the push default to simple i.e. push only the current branch. 91 git config --global push.default simple 92 93 # Remove everything currently in the gh-pages branch. 94 # GitHub is smart enough to know which files have changed and which files have 95 # stayed the same and will only update the changed files. So the gh-pages branch 96 # can be safely cleaned, and it is sure that everything pushed later is the new 97 # documentation. 98 CURRENTCOMMIT=`git rev-parse HEAD` 99 git reset --hard `git rev-list HEAD | tail -n 1` # Reset working tree to initial commit 100 git reset --soft $CURRENTCOMMIT # Move HEAD back to where it was 101 102 # Move doxy files into local gh-pages branch folder 103 mv ../../html-out/* . 104 105 # Need to create a .nojekyll file to allow filenames starting with an underscore 106 # to be seen on the gh-pages site. Therefore creating an empty .nojekyll file. 107 # Presumably this is only needed when the SHORT_NAMES option in Doxygen is set 108 # to NO, which it is by default. So creating the file just in case. 109 echo "" > .nojekyll 110 111 echo 'Uploading documentation to the gh-pages branch...' 112 # Add everything in this directory (the Doxygen code documentation) to the 113 # gh-pages branch. 114 # GitHub is smart enough to know which files have changed and which files have 115 # stayed the same and will only update the changed files. 116 git add --all 117 118 # Commit the added files with a title and description containing the Travis CI 119 # build number and the GitHub commit reference that issued this build. 120 git commit -m "Deploy code docs to GitHub Pages" 121 122 # Force push to the remote gh-pages branch. 123 # The ouput is redirected to /dev/null to hide any sensitive credential data 124 # that might otherwise be exposed. 125 git push --force "https://${GH_REPO_TOKEN}@${GH_REPO_REF}" > /dev/null 2>&1 126else 127 echo '' >&2 128 echo 'Warning: No documentation (html) files have been found!' >&2 129 echo 'Warning: Not going to push the documentation to GitHub!' >&2 130 exit 1 131fi 132