doc: filter known issues

make the doc build process quiet and add filtering of known (Sphinx)
issues.  Scripting comes from the open source Zephyr project.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>

Author: dbkinder

doc/.gitignore

@@ -2,3 +2,5 @@ doxygen
 _build
 *.bak
 *.sav
+*.log
+*.warnings

doc/.known-issues/README

@@ -0,0 +1,55 @@
+This directory contains configuration files to ignore errors found in
+the build and test process which are known to the developers and for
+now can be safely ignored.
+
+To use:
+
+ $ cd <build directory>
+ $ make SOMETHING >& result
+ $ scripts/filter-known-issues.py result
+
+It is included in the source tree so if anyone has to submit anything
+that triggers some kind of error that is a false positive, it can
+include the "ignore me" file, properly documented.
+
+Each file can contain one or more multiline Python regular expressions
+(https://docs.python.org/2/library/re.html#regular-expression-syntax)
+that match an error message. Multiple regular expressions are
+separated by comment blocks (that start with #). Note that an empty
+line still is considered part of the multiline regular expression.
+
+For example
+
+---beginning---
+#
+# This testcase always fails, pending fix ZEP-1234
+#
+.*/tests/kernel/grumpy .* FAIL
+#
+# Documentation issue, masks:
+#
+# /home/e/inaky/z/kernel.git/doc/api/io_interfaces.rst:28: WARNING: Invalid definition: Expected identifier in nested name. [error at 19]
+#  struct dev_config::@65  dev_config::bits
+#  -------------------^
+#
+^(?P<filename>.+/doc/api/io_interfaces.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
+^\s+struct dev_config::@[0-9]+  dev_config::bits.*
+^\s+-+\^
+---end---
+
+Note you want to:
+
+- use relateive paths; instead of
+  /home/me/mydir/zephyr/something/somewhere.c you will want
+  ^.*/something/somewhere.c (as they will depend on where it is being
+  built)
+
+- Replace line numbers with [0-9]+, as they will change
+
+- (?P<filename>[-._/\w]+/something/somewhere.c) saves the match on
+  that file path in a "variable" called 'filename' that later you can
+  match with (?P=filename) if you want to match multiple lines of the
+  same error message.
+
+Can get really twisted and interesting in terms of regexps; they are
+powerful, so start small :)

doc/.known-issues/doc/hypercall.conf

@@ -0,0 +1,37 @@
+#
+# Hypercall
+#
+#
+# include/net/net_ip.h warnings
+#
+^(?P<filename>[-._/\w]+/api/hypercall_api.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
+^[ \t]*
+^[ \t]*\^
+^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
+^[ \t]*
+^[ \t]*\^
+^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
+^[ \t]*
+^[ \t]*\^
+^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
+^[ \t]*
+^[ \t]*\^
+^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected end of definition. \[error at [0-9]+]
+^.*vhm_request.reqs
+^[- \t]*\^
+#
+^(?P<filename>[-._/\w]+/api/hypercall_api.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
+^[ \t]*
+^[ \t]*\^
+^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
+^[ \t]*
+^[ \t]*\^
+^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected end of definition. \[error at [0-9]+]
+^.*hc_ptdev_irq.is
+^[- \t]*\^
+^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected end of definition. \[error at [0-9]+]
+^.*hc_ptdev_irq.is.intx
+^[- \t]*\^
+^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected end of definition. \[error at [0-9]+]
+^.*hc_ptdev_irq.is.msix
+^[- \t]*\^

doc/Makefile

@@ -23,7 +23,7 @@ help:
 .PHONY: help Makefile
 
 pullsource:
-	scripts/pullsource.sh
+	$(Q)scripts/pullsource.sh
 
 
 # Generate the doxygen xml (for Sphinx) and copy the doxygen html to the
@@ -32,6 +32,11 @@ pullsource:
 doxy: pullsource
 	$(Q)(cat acrn.doxyfile) | doxygen -  2>&1
 
+html: doxy
+	$(Q)$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)" "$(SPHINXOPTS)" $(O) > doc.log 2>&1
+	$(Q)./scripts/filter-doc-log.sh doc.log
+
+
 # Remove generated content (Sphinx and doxygen)
 
 clean:

doc/scripts/filter-doc-log.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+
+# run the filter-known-issues.py script to remove "expected" warning
+# messages from the output of the document build process and write
+# the filtered output to stdout
+#
+# Only argument is the name of the log file saved by the build.
+
+KI_SCRIPT=scripts/filter-known-issues.py
+CONFIG_DIR=.known-issues/doc
+
+LOG_FILE=$1
+
+if [ -z "${LOG_FILE}" ]; then
+        echo "Error in $0: missing input parameter <logfile>"
+        exit 1
+fi
+
+# When running in background, detached from terminal jobs, tput will
+# fail; we usually can tell because there is no TERM env variable.
+if [ -z "${TERM:-}" -o "${TERM:-}" = dumb ]; then
+    TPUT="true"
+    red=''
+    green=''
+else
+    TPUT="tput"
+    red='\E[31m'
+    green='\e[32m'
+fi
+
+if [ -s "${LOG_FILE}" ]; then
+   $KI_SCRIPT --config-dir ${CONFIG_DIR} ${LOG_FILE} > doc.warnings 2>&1
+   if [ -s doc.warnings ]; then
+	   echo
+	   echo -e "${red}New errors/warnings found, please fix them:"
+	   echo -e "=============================================="
+	   $TPUT sgr0
+	   echo
+	   cat doc.warnings
+	   echo
+   else
+	   echo -e "${green}No new errors/warnings."
+	   $TPUT sgr0
+   fi
+
+else
+   echo "Error in $0: logfile \"${LOG_FILE}\" not found."
+   exit 1
+fi