summaryrefslogtreecommitdiff
path: root/doc/ghdeploydoxy.sh
blob: d898090185d89708703c44154c32ef328621c124 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
#!/bin/bash
################################################################################
# Notes         :
# 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.
# - A gh-pages branch should already exist.
#
# Required global variables:
# - 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       : The GitHub application token.
#
# 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

GH_REPO_NAME=
GH_REPO_REF=
GH_REPO_TOKEN=

usage() { echo "Usage: `basename $0` options (-n value) (-r value) (-t value)" 1>&2; exit 1; }

if ( ! getopts ":n:r:t:" opt); then
      usage
fi

while getopts :n:r:t: opt; do
  case $opt in
  n)
      GH_REPO_NAME=$OPTARG
      ;;
  r)
      GH_REPO_REF=$OPTARG
      ;;
  t)
      GH_REPO_TOKEN=$OPTARG
      ;;
  *)
      usage
      ;;
  esac
done

shift $((OPTIND - 1))

[ -n "$GH_REPO_NAME" ] || {
    echo "ERROR: -n GH_REPO_NAME is not defined" >/dev/stderr
    exit 1
}

[ -n "$GH_REPO_REF" ] || {
    echo "ERROR: -r GH_REPO_REF is not defined" >/dev/stderr
    exit 1
}

[ -n "$GH_REPO_TOKEN" ] || {
    echo "ERROR: -t GH_REPO_TOKEN is not defined" >/dev/stderr
    exit 1
}

################################################################################
##### 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-out" ] && [ -f "html-out/index.html" ]; then

    # 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

    # 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.
    CURRENTCOMMIT=`git rev-parse HEAD`
    git reset --hard `git rev-list HEAD | tail -n 1` # Reset working tree to initial commit
    git reset --soft $CURRENTCOMMIT # Move HEAD back to where it was

    # Move doxy files into local gh-pages branch folder
    mv ../../html-out/* .

    # 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

    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"

    # 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