otp: Add support for warnings as errors for ex_doc

We check the output of ex_doc to see if there are any
warnings emitted and if there are then we exit the build.

Author: garazdawi

erts/configure

@@ -7331,7 +7331,6 @@ fi
 done
 
 if test -z "$EX_DOC"; then
-  EX_DOC="$ERL_TOP/make/ex_doc_wrapper"
   { printf "%s\n" "$as_me:${as_lineno-$LINENO}: WARNING: No 'ex_doc' command found: it will (optionally) be downloaded when building the HTML documentation " >&5
 printf "%s\n" "$as_me: WARNING: No 'ex_doc' command found: it will (optionally) be downloaded when building the HTML documentation " >&2;}
 fi

erts/configure.ac

@@ -474,7 +474,6 @@ fi
 
 AC_CHECK_PROGS(EX_DOC, ex_doc)
 if test -z "$EX_DOC"; then
-  EX_DOC="$ERL_TOP/make/ex_doc_wrapper"
   AC_MSG_WARN([No 'ex_doc' command found: it will (optionally) be downloaded when building the HTML documentation ])
 fi
 

lib/common_test/doc/Makefile

@@ -26,6 +26,7 @@ include $(ERL_TOP)/make/$(TARGET)/otp.mk
 include ../vsn.mk
 VSN=$(COMMON_TEST_VSN)
 APPLICATION=common_test
+EX_DOC_WARNINGS_AS_ERRORS=false
 
 # ----------------------------------------------------
 # Release Target

make/doc.mk

@@ -52,15 +52,17 @@ else
 DOC_TARGETS?=html
 endif
 
+EX_DOC_WARNINGS_AS_ERRORS?=true
+
 docs: $(DOC_TARGETS)
 
 chunks:
 
 HTML_DEPS?=$(wildcard $(APP_EBIN_DIR)/*.beam) $(wildcard *.md) $(wildcard */*.md) $(wildcard assets/*)
 
-$(HTMLDIR)/index.html: $(HTML_DEPS) docs.exs
-	$(gen_verbose)ERL_FLAGS="-pz $(ERL_TOP)/erts/ebin" \
-	  $(EX_DOC) $(EX_DOC_FORMATS) --homepage-url "$(INDEX_DIR)/index.html" "$(APPLICATION)" $(VSN) $(APP_EBIN_DIR) -o "$(HTMLDIR)" -c $(ERL_TOP)/make/ex_doc.exs
+$(HTMLDIR)/index.html: $(HTML_DEPS) docs.exs $(ERL_TOP)/make/ex_doc.exs
+	$(gen_verbose)EX_DOC_WARNINGS_AS_ERRORS=$(EX_DOC_WARNINGS_AS_ERRORS) ERL_FLAGS="-pz $(ERL_TOP)/erts/ebin" \
+	  $(ERL_TOP)/make/ex_doc_wrapper $(EX_DOC_FORMATS) --homepage-url "$(INDEX_DIR)/index.html" "$(APPLICATION)" $(VSN) $(APP_EBIN_DIR) -o "$(HTMLDIR)" -c $(ERL_TOP)/make/ex_doc.exs
 
 html: $(HTMLDIR)/index.html
 

make/ex_doc_wrapper

@@ -4,9 +4,9 @@ ARGS=("$@")
 
 set -eo pipefail {0}
 
-if command -v ex_doc &> /dev/null; then
-   exec ex_doc "${ARGS[@]}"
-else
+EX_DOC=$(command -v ex_doc || true)
+
+if [ -z "${EX_DOC}" ]; then
     echo -n "Could not find ex_doc! "
     read -p "Do you want to download latest ex_doc from github? (y/n)? " -n 1 -r
     echo
@@ -15,11 +15,35 @@ else
         if $ERL_TOP/otp_build download_ex_doc; then
             read -p "Press any key to continue..." -n 1 -r
             echo "continuing"
-            exec ex_doc "${ARGS[@]}"
+            EX_DOC=$(command -v ex_doc || true)
         else
             exit 1
         fi
     else
         exit 1
     fi
 fi
+
+## The below bash magic captures the output of stderr into OUTPUT while still printing
+## everything we get to stdout and stderr. This is done by:
+
+## 1. duplicating the stdout (1) and stderr (2) streams to fd 3 and 4 respectively.
+exec 3>&1 4>&2
+
+## Running the command where we redirect stderr to fd 1 and stdout to fd 3.
+## We then use tee on the stderr (which is now fd 1) to print that to fd 4
+OUTPUT="$( { "${EX_DOC}" "${ARGS[@]}"; } 2>&1 1>&3 | tee /dev/fd/4 )"
+
+## Close fd 3 and 4
+exec 3>&- 4>&-
+
+if [ "${EX_DOC_WARNINGS_AS_ERRORS}" != "false" ]; then
+    if echo "${OUTPUT}" | grep "warning:" 1>/dev/null; then
+        echo "ex_doc emitted warnings"
+        ## Touch the config file in order to re-trigger make
+        if [ -f "docs.exs" ]; then
+            touch "docs.exs"
+        fi
+        exit 1;
+    fi
+fi