New script to create documentation and report warnings (disregard exc…

…eptions)

- fix #266 (comment)
- addressing #266

- new script `tools/run_doxygen.sh`
- new make targets: "doc" and "doc_clean"

- continuous integration: travis-ci will now use the new script which fails on warnings, but disregards exceptions that are documented in the new file `doc/doxygen_exceptions.txt`

- currently, there is one known exception, see #267

- moved `Doxyfile` to `doc/` (addressing #89)

.gitignore

@@ -29,6 +29,7 @@ sw_test
 
 # Doxygen documentation files: they should be produced locally
 doc/html/*
+doc/log_doxygen.log
 
 # Binary files
 SOILWAT2

.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

README.md

@@ -88,7 +88,7 @@ Some recent references
 <a name="get_documentation"></a>
 ### 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:
 <a name="code_documentation"></a>
 #### 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
 
 <br>
 

doc/doxygen_exceptions.txt

@@ -0,0 +1 @@
+warning: Unexpected html tag <img> found within <a href=...> context

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

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