doc/ghdeploydoxy.sh

   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.               #####
  26 echo 'Setting up the script...'
  27 # Exit with nonzero exit code if anything fails
  28 set -e
  29
  30 GH_REPO_NAME=
  31 GH_REPO_REF=
  32 GH_REPO_TOKEN=
  33
  34 usage() { echo "Usage: `basename $0` options (-n value) (-r value) (-t value)" 1>&2; exit 1; }
  35
  36 if ( ! getopts ":n:r:t:" opt); then
  37       usage
  38 fi
  39
  40 while 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
  55 done
  56
  57 shift $((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.
  79 if [ -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
 126 else
 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
 131 fi