Script documentation generation and UML support (#992)

Documentation is now generated by invoking a shell script
which takes care of all the plumbing.
There is now also support of inlineing PlantUML syntax with
Doxygen. This inlining takes the form of
@startuml{imagename.png}
'PlantUML specific syntax'
@enduml
The inlineing can be made in C syntax comment blocks.
Doxygen will then include the generated UML diagram when
rendering the HTML documentation.
All generated images will be placed under Documentation/img
which is the default search path for Doxygen.

.ci/doxygen.groovy

@@ -1,22 +1,9 @@
 #!groovy
 def call(config) {
 	config.pr.setBuildStatus(config, 'PENDING', 'Toll gate (Documentation)', 'Generating...', '${BUILD_URL}flowGraphTable/')
-	// Generate doxygen file for Raspberry Pi configure command
-	sh """#!/bin/bash +x
+	sh """#!/bin/bash
 				cd ${config.repository_root}
-				echo -e "/**\n * @defgroup RaspberryPiGateway Raspberry Pi Gateway\n * @ingroup MyConfigGrp\n * @brief Configuration options for the Raspberry Pi Gateway\n@{\n@verbatim" > configure.h
-				grep -A999 '<<EOF' configure | grep -B999 EOF | grep -v 'EOF' >> configure.h
-				echo -e "@endverbatim\n@}*/\n" >> configure.h"""
-	sh """#!/bin/bash +x
-				cd ${config.repository_root}
-				export PROJECTNUMBER=\$(
-					if [[ \$(git rev-parse --abbrev-ref HEAD) == "master" ]]; then
-						git describe --tags ;
-					else
-						git rev-parse --short HEAD ;
-					fi
-				)
-				echo 'WARN_LOGFILE=doxygen.log' >> Doxyfile && doxygen"""
+				Documentation/doxygen.sh"""
 	warnings canComputeNew: false, canResolveRelativePaths: false,
 		defaultEncoding: '',
 		excludePattern: '''.*/sha204_library\\.h,.*/drivers/Linux/.*,.*/cores/esp8266/.*,hardware/.*''',

.gitattributes

@@ -10,7 +10,6 @@
 *.xml text
 *.lua text
 
-
 # Denote all files that are truly binary and should not be modified.
 *.png binary
 *.jpg binary
@@ -20,3 +19,4 @@
 *.svg binary
 *.woff binary
 *.epg binary
+*.jar binary

.gitignore

@@ -9,3 +9,4 @@ build
 bin
 *.sublime-workspace
 .idea
+doxygen.log

Documentation/doxygen.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+## Invoke from project root, e.g Documentation/doxygen.sh
+
+# Generate doxygen file for Raspberry Pi configure command
+echo -e "/**\n * @defgroup RaspberryPiGateway Raspberry Pi Gateway\n * @ingroup MyConfigGrp\n * @brief Configuration options for the Raspberry Pi Gateway\n@{\n@verbatim" > configure.h
+				grep -A999 '<<EOF' configure | grep -B999 EOF | grep -v 'EOF' >> configure.h
+				echo -e "@endverbatim\n@}*/\n" >> configure.h
+
+# Generate version information
+export PROJECTNUMBER=$(
+	if [[ $(git rev-parse --abbrev-ref HEAD) == "master" ]]; then
+		git describe --tags ;
+	else
+		git rev-parse --short HEAD ;
+	fi
+)
+
+# Generate any UML diagrams in the code tree that has the proper tags
+export PLANTUML_JAR_PATH=Documentation/plantuml.jar
+java -Djava.awt.headless=true -jar $PLANTUML_JAR_PATH -failfast2 -nbthread auto -o "$PWD/Documentation/img" "./**.(c|cpp|dox|h|hpp|ino)"
+
+# Launch Doxygen (assumed to be in the PATH)
+doxygen
+
+# Show any warnings created
+cat doxygen.log
+
+# Clean up autogenerated (temporary) artifacts
+rm configure.h

Doxyfile

@@ -220,7 +220,8 @@ TAB_SIZE               = 4
 # "Side Effects:". You can put \n's in the value part of an alias to insert
 # newlines.
 
-ALIASES                =
+ALIASES                = "startuml{1}=\image html \1\n\image latex \1\n\if DontIgnorePlantUMLCode"
+ALIASES               += "enduml=\endif"
 
 # This tag can be used to specify a number of word-keyword mappings (TCL only).
 # A mapping has the form "name=value". For example adding "class=itcl::class"
@@ -731,7 +732,7 @@ WARN_FORMAT            = "$file:$line: $text"
 # messages should be written. If left blank the output is written to standard
 # error (stderr).
 
-WARN_LOGFILE           =
+WARN_LOGFILE           = doxygen.log
 
 #---------------------------------------------------------------------------
 # Configuration options related to the input files
@@ -2289,3 +2290,6 @@ GENERATE_LEGEND        = YES
 # This tag requires that the tag HAVE_DOT is set to YES.
 
 DOT_CLEANUP            = YES
+
+# PlantUML executable
+PLANTUML_JAR_PATH      = $(PLANTUML_JAR_PATH)