From d3b0cd4827171d3f4ed39339a3d33c6342dfaa23 Mon Sep 17 00:00:00 2001
From: "David B. Kinder" <david.b.kinder@intel.com>
Date: Thu, 21 Sep 2017 11:55:15 -0700
Subject: [PATCH] doc: move docgen filter out of shippable script

Because of known issues with Sphinx/Breathe tools we're using to
generate doxygen-based comments for our API documentation, we're getting
a bevy of warning messages written out. As a workaround for our CI
system, we created a filter-known-issues.py script to remove "expected"
warnings from the output.

This patch moves calling that filter script into the doc generation
Makefile so folks making local builds of the docs won't be tripped up by
all the warning messages either.  Output of the "make htmldocs" command
is now filtered so only "unexpected" errors and warnings will be shown.

(See https://github.com/sphinx-doc/sphinx/issue/2682 and
sphinx-doc/sphinx#2683i for the Sphinx/Breathe issues.)

Fixes #1527

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
---
 .shippable.yml                | 10 ++--------
 doc/Makefile                  |  3 ++-
 doc/scripts/filter-doc-log.sh | 26 ++++++++++++++++++++++++++
 3 files changed, 30 insertions(+), 9 deletions(-)
 create mode 100755 doc/scripts/filter-doc-log.sh

diff --git a/.shippable.yml b/.shippable.yml
index 7a4cdfee776..7f042340022 100644
--- a/.shippable.yml
+++ b/.shippable.yml
@@ -40,17 +40,11 @@ build:
             echo "Building a Pull Request";
             echo "- Building Documentation";
             echo "Commit range:" ${COMMIT_RANGE}
-            make htmldocs > doc.log 2>&1;
-            ./scripts/filter-known-issues.py --config-dir .known-issues/doc/ doc.log > doc.warnings;
-
-            if [ "$?" != 0 ]; then
-              echo " ==> Error running filter script"
-              exit 1
-            fi;
+            make htmldocs > doc.warnings 2>&1;
             if [ -s doc.warnings ]; then
               echo " => New documentation warnings/errors";
             fi;
-            echo "- Verify commit message and coding style";
+            echo "- Verify commit message, coding style, doc build";
             ./scripts/ci/check-compliance.py --commits ${COMMIT_RANGE} || true;
           fi;
       - >
diff --git a/doc/Makefile b/doc/Makefile
index 624e12c7608..9e9ff73c644 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -79,7 +79,8 @@ kconfig: scripts/genrest/genrest.py
 prep: doxy content kconfig
 
 html: content kconfig
-	$(Q)$(SPHINXBUILD) -t $(DOC_TAG) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	$(Q)$(SPHINXBUILD) -t $(DOC_TAG) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html > doc.log 2>&1;
+	$(Q)./scripts/filter-doc-log.sh doc.log
 	@rm -rf samples
 	@rm -rf boards
 
diff --git a/doc/scripts/filter-doc-log.sh b/doc/scripts/filter-doc-log.sh
new file mode 100755
index 00000000000..1a7fe20a14e
--- /dev/null
+++ b/doc/scripts/filter-doc-log.sh
@@ -0,0 +1,26 @@
+#!/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=${ZEPHYR_BASE}/scripts/filter-known-issues.py
+CONFIG_DIR=${ZEPHYR_BASE}/.known-issues/doc
+
+LOG_FILE=$1
+
+if [ -z "${LOG_FILE}" ]; then
+        echo "Error in $0: missing input parameter <logfile>"
+        exit 1
+fi
+
+if [ -e "${LOG_FILE}" ]; then
+   if [ -s "${LOG_FILE}" ]; then
+      $KI_SCRIPT --config-dir ${CONFIG_DIR} ${LOG_FILE}
+   fi
+else
+   echo "Error in $0: logfile \"${LOG_FILE}\" not found."
+   exit 1
+fi