Adding doxygen docs

.ci/build_docs.sh

@@ -0,0 +1,103 @@
+#!/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 "travis@travis-ci.org"
+
+# 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

.travis.yml

@@ -53,6 +53,12 @@ install:
 script:
 - cd "${TRAVIS_BUILD_DIR}"
 - .ci/travis.sh
+
+after_success:
+- echo "${TRAVIS_BRANCH}"
+- echo "${TRAVIS_PULL_REQUEST}"
+- if [[ "${TRAVIS_BRANCH}" == "master" && "${TRAVIS_PULL_REQUEST}" == "false" && "$DEPLOY_MAT" == "yes"]] ; then echo "Updating docs" &&  cd $TRAVIS_BUILD_DIR && .ci/build_docs.sh ; fi
+
 deploy:
   provider: releases
   api_key:

docs/.gitignore

@@ -0,0 +1,2 @@
+/html/*
+/latex/*

docs/mainpage.md

@@ -0,0 +1,21 @@
+# Introduction
+
+This is the Doxygen API documentation for CLI11 parser. There is a friendly introduction to CLI11 on the [Github page](https://github.com/henryiii/CLI11).
+
+The main classes are:
+
+| Name          | Where used                          |
+|---------------|-------------------------------------|
+|CLI::Option    | Options, stored in the app          |
+|CLI::App       | The main application or subcommands |
+
+
+Groups of related topics:
+
+| Name                 | Description                                    |
+|----------------------|------------------------------------------------|
+| @ref error_group     | Errors that can be thrown                      |
+| @ref validator_group | Common validators used in CLI::Option::check() |
+
+
+

include/CLI/App.hpp

@@ -33,7 +33,7 @@ typedef std::unique_ptr<Option> Option_p;
 typedef std::unique_ptr<App> App_p;
 
 /// Creates a command line program, with very few defaults.
-/** To use, create a new Program() instance with argc, argv, and a help description. The templated
+/** To use, create a new `Program()` instance with `argc`, `argv`, and a help description. The templated
 *  add_option methods make it easy to prepare options. Remember to call `.start` before starting your
 * program, so that the options can be evaluated and the help option doesn't accidentally run your program. */
 class App {

include/CLI/Error.hpp

@@ -11,6 +11,12 @@ namespace CLI {
 
 // Error definitions
 
+/// @defgroup error_group Errors
+/// @brief Errors thrown by CLI11
+///
+/// These are the errors that can be thrown. Some of them, like CLI::Success, are not really errors.
+/// @{
+
 /// All errors derive from this one
 struct Error : public std::runtime_error {
     int exit_code;
@@ -18,8 +24,7 @@ struct Error : public std::runtime_error {
     Error(std::string parent, std::string name, int exit_code=255, bool print_help=true) : runtime_error(parent + ": " + name), exit_code(exit_code), print_help(print_help) {}
 };
 
-// Construction errors (not in parsing)
-
+/// Construction errors (not in parsing)
 struct ConstructionError : public Error {
     // Using Error::Error constructors seem to not work on GCC 4.7
     ConstructionError(std::string parent, std::string name, int exit_code=255, bool print_help=true) : Error(parent, name, exit_code, print_help) {}
@@ -107,5 +112,6 @@ struct OptionNotFound : public Error {
     OptionNotFound(std::string name) : Error("OptionNotFound", name, 4) {}
 };
 
+/// @}
 
 }

include/CLI/Validators.hpp

@@ -17,6 +17,12 @@
 namespace CLI {
 
 
+/// @defgroup validator_group Validators
+/// @brief Some validators that are provided
+///
+/// These are simple `bool(std::string)` validators that are useful.
+/// @{
+
 /// Check for an existing file
 bool ExistingFile(std::string filename) {
     struct stat buffer;   
@@ -78,4 +84,6 @@ std::function<bool(std::string)> Range(T max) {
     return Range((T) 0, max);
 }
 
+/// @}
+
 }