Merge pull request #62 from GeorgKreuzmayr/feature/doxygen

Automatic Code Documentation

.travis.yml

@@ -7,6 +7,15 @@ jobs:
       mono: none
       os: linux
       script: chmod +x ./Travis/test_linux.sh && ./Travis/test_linux.sh
+      before_deploy:
+        - sudo apt-get install doxygen doxygen-doc graphviz
+      deploy:
+        skip_cleanup: true
+        provider: script
+        script: chmod +x ./Travis/deploy_documentation.sh && ./Travis/deploy_documentation.sh
+        on:
+          tags: true
+          all_branches: true
     - stage: windows_build
       mono: none
       os: windows

Travis/deploy_documentation.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+
+# Generate the docs only if master, the travis_build_docs is true and we can use secure variables
+
+set -ev
+declare -r SSH_FILE="$(mktemp -u $HOME/.ssh/travis_temp_ssh_key_XXXX)"
+
+echo -e "$SSH_PRIVATE" > "$SSH_FILE"
+
+# Enable SSH authentication
+chmod 600 "$SSH_FILE" \
+  && printf "%s\n" \
+       "Host github.com" \
+       "  IdentityFile $SSH_FILE" \
+       "  LogLevel ERROR" >> ~/.ssh/config
+
+ssh-keyscan github.com >> "$HOME/.ssh/known_hosts"
+
+chmod +x "$TRAVIS_BUILD_DIR/Travis/generate_documentation.sh"
+"$TRAVIS_BUILD_DIR/Travis/generate_documentation.sh" || travis_terminate 1

Travis/generate_documentation.sh

@@ -0,0 +1,102 @@
+#!/bin/sh
+################################################################################
+# Title         : generate_documentation.sh
+# Date created  : 2017
+# Notes         : original script from Jeroen de Bruijn
+__AUTHOR__="Francesco Romano"
+# Preconditions:
+# - Packages doxygen doxygen-doc 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 -ev
+
+
+GH_REPO_ORG=`echo $TRAVIS_REPO_SLUG | cut -d "/" -f 1`
+GH_REPO_NAME=`echo $TRAVIS_REPO_SLUG | cut -d "/" -f 2`
+GH_REPO_REF="github.com/$GH_REPO_ORG/$GH_REPO_NAME.git"
+DOXYFILE="$TRAVIS_BUILD_DIR/documentation/Doxyfile"
+
+
+# Get the current gh-pages branch
+git clone -b gh-pages [email protected]:$GH_REPO_ORG/$GH_REPO_NAME.git code_docs
+cd code_docs
+
+
+# Set the push default to simple i.e. push only the current branch.
+##### Configure git.
+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]"
+
+# go back to first commit
+git reset --hard `git rev-list --max-parents=0 --abbrev-commit HEAD`
+
+# 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 "[email protected]:$GH_REPO_ORG/$GH_REPO_NAME.git" > /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