Merge branch 'bugfix/ci_sphinx_warnings' into 'master'

ci: Add new check_doc_warnings.sh script, pre-process log lines

See merge request !1258

.gitignore

@@ -27,6 +27,7 @@ examples/**/build
 docs/_build/
 docs/doxygen-warning-log.txt
 docs/sphinx-warning-log.txt
+docs/sphinx-warning-log-sanitized.txt
 docs/xml/
 docs/man/
 

.gitlab-ci.yml

@@ -179,6 +179,7 @@ build_docs:
     paths:
       - docs/doxygen-warning-log.txt
       - docs/sphinx-warning-log.txt
+      - docs/sphinx-warning-log-sanitized.txt
       - docs/_build/html
     expire_in: 1 mos
   script:
@@ -188,18 +189,7 @@ build_docs:
     - test $(cat doxygen-warning-log.txt | wc -l) -eq 0 || ( echo "Doxygen pass had some warnings:" && cat doxygen-warning-log.txt && false )
     - make gh-linkcheck
     - make html
-    # If there are Sphinx warnings, print them and bail out
-    # Ignore warnings (sphinx-known-warnings.txt) already reported in:
-    # https://github.com/sphinx-doc/sphinx/issues/2683
-    # https://github.com/sphinx-doc/sphinx/issues/4041
-    # If a new warning has to be added, then it should be documented as above
-    # Note: this check is not clever enough to ignore the same warning
-    #       but reported for different line of documentation. 
-    #       If s warning stays the same and the line number has changed,
-    #       then update 'sphinx-known-warnings.txt' to reflect the new lines numbers.
-    - DIFF_FORMAT="--changed-group-format=%<%> --unchanged-group-format="
-    - LOG_DIFF=$(diff $DIFF_FORMAT sphinx-known-warnings.txt sphinx-warning-log.txt)
-    - test -z "$LOG_DIFF" || ( echo "Sphinx pass had some new warnings:" && echo "$LOG_DIFF" && false )
+    - ./check_doc_warnings.sh
 
 test_nvs_on_host:
   stage: test

docs/check_doc_warnings.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+#
+# Check for Documentation warnings:
+# doxygen-warning-log.txt should be an empty file
+# sphinx-warning-log.txt should only contain (fuzzy) matches to sphinx-known-warnings.txt
+cd "$(dirname $0)"
+RESULT=0
+STARS='***************************************************'
+
+if [ -s doxygen-warning-log.txt ]; then
+    echo "$STARS"
+    echo "Build failed due to doxygen warnings:"
+    cat doxygen-warning-log.txt
+    echo "$STARS"
+    RESULT=1
+fi
+
+# Remove escape characters, file paths, line numbers from
+# the Sphinx warning log
+# (escape char removal from https://www.commandlinefu.com/commands/view/6141/remove-color-codes-special-characters-with-sed
+sed -r 's:\x1B\[[0-9;]*[mK]::g' sphinx-warning-log.txt | \
+    sed -E "s~${IDF_PATH}~\${IDF_PATH}~" | \
+    sed -E "s/:[0-9]+:/:line:/" > sphinx-warning-log-sanitized.txt
+
+# diff sanitized warnings, ignoring lines which only appear in sphinx-known-warnings.txt
+
+# format is to display only lines new or changed in second argument
+DIFF_FORMAT="--unchanged-line-format= --old-line-format= --new-line-format=%L"
+
+SPHINX_WARNINGS=$(diff $DIFF_FORMAT sphinx-known-warnings.txt sphinx-warning-log-sanitized.txt)
+if ! [ -z "$SPHINX_WARNINGS" ]; then
+    echo "$STARS"
+    echo "Build failed due to new/different Sphinx warnings:"
+    echo "$SPHINX_WARNINGS"
+    echo "$STARS"
+    RESULT=1
+    echo "(Check files sphinx-known-warnings.txt and sphinx-warning-log.txt for full details.)"
+fi
+
+exit $RESULT
+

docs/sphinx-known-warnings.txt

@@ -1,9 +1,25 @@
-_build/inc/esp_a2dp_api.inc:26: WARNING: Invalid definition: Expected identifier in nested name. [error at 21]
+# File contains known/allowed Sphinx warnings.
+#
+# Build will fail if sphinx-warning-log.txt contains any lines
+# which are not in this file. Lines are pre-sanitized by
+# check_doc_warnings.sh to remove formatting, paths, line numbers.
+#
+# Warnings in this file must be in the same overall order as the log file.
+#
+
+#
+# Sphinx known issue https://github.com/sphinx-doc/sphinx/issues/2683\
+#
+_build/inc/esp_a2dp_api.inc:line: WARNING: Invalid definition: Expected identifier in nested name. [error at 21]
   union esp_a2d_mcc_t::@1  esp_a2d_mcc_t::cie
   ---------------------^
-_build/inc/esp_bt_defs.inc:11: WARNING: Invalid definition: Expected identifier in nested name. [error at 21]
+_build/inc/esp_bt_defs.inc:line: WARNING: Invalid definition: Expected identifier in nested name. [error at 21]
   union esp_bt_uuid_t::@0  esp_bt_uuid_t::uuid
   ---------------------^
-/builds/idf/esp-idf/docs/api-reference/storage/sdmmc.rst:24: WARNING: cpp:typeOrConcept targets a member (sdmmc_host_t::slot).
-/builds/idf/esp-idf/docs/api-reference/storage/sdmmc.rst:24: WARNING: cpp:typeOrConcept targets a member (sdmmc_host_t::slot).
-/builds/idf/esp-idf/docs/api-reference/storage/sdmmc.rst:24: WARNING: cpp:typeOrConcept targets a member (sdmmc_host_t::slot).
+
+#
+# Sphinx known issue https://github.com/sphinx-doc/sphinx/issues/4041
+#
+${IDF_PATH}/docs/api-reference/storage/sdmmc.rst:line: WARNING: cpp:typeOrConcept targets a member (sdmmc_host_t::slot).
+${IDF_PATH}/docs/api-reference/storage/sdmmc.rst:line: WARNING: cpp:typeOrConcept targets a member (sdmmc_host_t::slot).
+${IDF_PATH}/docs/api-reference/storage/sdmmc.rst:line: WARNING: cpp:typeOrConcept targets a member (sdmmc_host_t::slot).