diff --git a/.gitignore b/.gitignore
index 37bb43b28..631b7faae 100644
--- a/.gitignore
+++ b/.gitignore
@@ -29,6 +29,7 @@ sw_test
# Doxygen documentation files: they should be produced locally
doc/html/*
+doc/log_doxygen.log
# Binary files
SOILWAT2
diff --git a/.travis.yml b/.travis.yml
index 9a0603c52..5786ca932 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -47,10 +47,7 @@ script:
# determine code coverage of unit tests
- make clean cov test_run
# check that doxygen generates documentation without warnings
- # note: doxygen version on travis-ci is currently 1.8.6 (instead of 1.8.15),
- # thus, warnings about unsupported tags are ok, but we first need to downgrade the Doxyfile
- - if [[ $(doxygen --version) != "1.8.15" ]]; then doxygen -u Doxyfile &>/dev/null; fi
- - doxygen Doxyfile | grep -wF "warning"
+ - make doc
before_cache:
# don't cache generated documentation files
diff --git a/README.md b/README.md
index d26db6e8a..790e5f97e 100644
--- a/README.md
+++ b/README.md
@@ -88,7 +88,7 @@ Some recent references
### Documentation
* Use [doxygen][] to generate help pages (locally) on the command-line with
- `doxygen Doxyfile`, but don't push them to the repository
+ `make doc` (which basically runs `doxygen doc/Doxyfile`)
* View documentation in your browser by opening `doc/html/index.html`
@@ -129,12 +129,17 @@ You can help us in different ways:
#### Code documentation
* Use [doxygen][] to write inline documentation
- * Make sure that new documentation creates `doxygen` documentation without
- warnings, i.e., `doxygen Doxyfile | grep warning` should be empty, and
- that newly created and amended documentation displays as intended by
- opening `doc/html/index.html` and navigating to the item in question
- * Use regular c-style comments to document to code
+ * Make sure that new documentation results in `doxygen` documentation without
+ warnings, i.e., `make doc` is successful
+ (it basically checks that `doxygen doc/Doxyfile | grep warning` is empty).
+ Make also sure that newly created and amended documentation displays
+ as intended by opening `doc/html/index.html` and navigating to the item
+ in question
+
+ * Keep `doc/html/` local, i.e., don't push to the repository
+
+ * Use regular c-style comments to additionally document code
diff --git a/Doxyfile b/doc/Doxyfile
similarity index 100%
rename from Doxyfile
rename to doc/Doxyfile
diff --git a/doc/doxygen_exceptions.txt b/doc/doxygen_exceptions.txt
new file mode 100755
index 000000000..ba9333dbf
--- /dev/null
+++ b/doc/doxygen_exceptions.txt
@@ -0,0 +1 @@
+warning: Unexpected html tag found within context
diff --git a/makefile b/makefile
index 0d4e16010..b3819595a 100644
--- a/makefile
+++ b/makefile
@@ -9,6 +9,8 @@
# 'testing/' folder
# make bint_run same as 'make bint' plus execute the binary in testing/
#
+# make doc create html documentation for SOILWAT2 using doxygen
+#
# make lib create SOILWAT2 library
#
# make test compile unit tests in 'test/ folder (with googletest)
@@ -29,6 +31,7 @@
# files, libraries, and the binary exe(s)
# make test_clean delete test files and libraries
# make cov_clean delete files associated with code coverage
+# make doc_clean delete documentation
#-------------------------------------------------------------------------------
uname_m = $(shell uname -m)
@@ -252,6 +255,9 @@ cov_run : cov
./tools/run_gcov.sh
+.PHONY : doc
+doc :
+ ./tools/run_doxygen.sh
.PHONY : clean1
@@ -285,6 +291,10 @@ cleaner : clean1 clean2 bint_clean test_clean cov_clean
.PHONY : clean
clean : cleaner
+.PHONY : doc_clean
+doc_clean :
+ -@$(RM) -fr doc/html/
+ -@$(RM) -f doc/log_doxygen.log
.PHONY : help
diff --git a/tools/run_doxygen.sh b/tools/run_doxygen.sh
new file mode 100755
index 000000000..7cbd12877
--- /dev/null
+++ b/tools/run_doxygen.sh
@@ -0,0 +1,48 @@
+#!/bin/bash
+
+# Create documentation using doxygen and report any errors/warnings except
+# those warnings/errors listed as exceptions (doc/doxygen_exceptions.txt)
+
+doc_path="doc" # path to documentation
+doxy=${doc_path}"/Doxyfile" # Doxyfile
+log=${doc_path}"/log_doxygen.log" # logfile for doxygen output
+log_tmp=${doc_path}"/log_doxygen_tmp.log"
+doxexcept=${doc_path}"/doxygen_exceptions.txt" # filename that lists exceptions (one per line)
+
+
+# Don't use set if run locally, e.g., with `make doc`
+if [ ${CI} ]; then
+ set -ev
+ # The -e flag causes the script to exit as soon as one command returns a non-zero exit code
+ # The -v flag makes the shell print all lines in the script before executing them
+fi
+
+# Downgrade Doxyfile in case this runs an old doxygen version, e.g.,
+# travis-ci is currently on 1.8.6 (instead of 1.8.15)
+if [[ $(doxygen --version) != "1.8.15" ]]
+then
+ doxygen -u ${doxy} &>/dev/null
+fi
+
+# Run doxygen and pipe all output to a log file
+doxygen ${doxy} > ${log} 2>&1
+
+# Eliminate warnings/errors that are known exceptions
+# Make sure that there is such a (readable) file
+if [ -r ${doxexcept} ]; then
+ # Make sure that there are exceptions in the file
+ if [ $(wc -l < ${doxexcept}) -ne 0 ]; then
+ # Remove exceptions from the logfile
+ grep -v -f ${doxexcept} ${log} > ${log_tmp}
+ mv ${log_tmp} ${log}
+ rm -f ${log_tmp}
+ fi
+fi
+
+
+# Examine log file for remaining warnings/errors
+warnings=$(grep "warning\|error" ${log})
+
+if [ -n "${warnings}" ]; then
+ echo ${warnings}
+fi