Fail CI build on Sphinx warnings

.gitlab-ci.yml

@@ -175,16 +175,31 @@ build_docs:
   tags:
     - build_docs
   artifacts:
+    when: always
     paths:
+      - docs/doxygen-warning-log.txt
+      - docs/sphinx-warning-log.txt
       - docs/_build/html
     expire_in: 1 mos
   script:
     - cd docs
     - doxygen
-    # If not building master branch, and there are Doxygen warnings, print them and bail out
-    - test -n $IS_PRIVATE && test $(cat doxygen-warning-log.txt | wc -l) -eq 0 || ( echo "Doxygen pass had some warnings:" && cat doxygen-warning-log.txt && false )
+    # If there are Doxygen warnings, print them and bail out
+    - 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 )
 
 test_nvs_on_host:
   stage: test

docs/api-guides/build-system.rst

@@ -358,7 +358,7 @@ Warning On Undefined Variables
 
 By default, the build process will print a warning if an undefined variable is referenced (like ``$(DOES_NOT_EXIST)``). This can be useful to find errors in variable names.
 
-If you don't want this behaviour, it can be disabled by disabling :ref:`CONFIG_MAKE_WARN_UNDEFINED_VARIABLES`.
+If you don't want this behaviour, it can be disabled in menuconfig's top level menu under `SDK tool configuration`.
 
 Note that this option doesn't trigger a warning if ``ifdef`` or ``ifndef`` are used in Makefiles.
 

docs/api-reference/peripherals/spi_master.rst

@@ -66,6 +66,7 @@ In half duplex, the length of write phase and read phase are decided by ``trans_
 ``trans_conf.rx_length`` respectively. ** Note that a half duplex transaction with both a read and 
 write phase is not supported when using DMA. ** If such transaction is needed, you have to use one 
 of the alternative solutions:
+
   1. use full-duplex mode instead.
   2. disable the DMA by set the last parameter to 0 in bus initialization function just as belows:
      ``ret=spi_bus_initialize(VSPI_HOST, &buscfg, 0);``  
@@ -109,8 +110,10 @@ Transaction data
 Normally, data to be transferred to or from a device will be read from or written to a chunk of memory
 indicated by the ``rx_buffer`` and ``tx_buffer`` members of the transaction structure. 
 When DMA is enabled for transfers, these buffers are highly recommended to meet the requirements as belows:
+
   1. allocated in DMA-capable memory using ``pvPortMallocCaps(size, MALLOC_CAP_DMA)``;
   2. 32-bit aligned (start from the boundary and have length of multiples of 4 bytes).
+
 If these requirements are not satisfied, efficiency of the transaction will suffer due to the allocation and 
 memcpy of temporary buffers.
 

docs/get-started/index.rst

@@ -207,7 +207,7 @@ Here are couple of tips on navigation and use of ``menuconfig``:
 
 .. note::
 
-    Most ESP32 development boards have a 40MHz crystal installed. However, some boards use a 26MHz crystal. If your board uses a 26MHz crystal, or you get garbage output from serial port after code upload, adjust the :ref:`CONFIG_ESP32_XTAL_FREQ` option in menuconfig.
+    Most ESP32 development boards have a 40MHz crystal installed. However, some boards use a 26MHz crystal. If your board uses a 26MHz crystal, or you get garbage output from serial port after code upload, adjust the :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` option in menuconfig.
 
 .. _get-started-build-flash:
 

docs/kconfiglib.py

@@ -69,6 +69,7 @@ might add it in a safe way as a client API instead."""
 import os
 import re
 import sys
+import platform
 
 # File layout:
 #
@@ -165,7 +166,8 @@ class Config(object):
         self.m = register_special_symbol(TRISTATE, "m", "m")
         self.y = register_special_symbol(TRISTATE, "y", "y")
         # DEFCONFIG_LIST uses this
-        register_special_symbol(STRING, "UNAME_RELEASE", os.uname()[2])
+        # changed os.uname to platform.uname for compatibility with Windows
+        register_special_symbol(STRING, "UNAME_RELEASE", platform.uname()[2])
 
         # The symbol with "option defconfig_list" set, containing a list of
         # default .config files

docs/sphinx-known-warnings.txt

@@ -0,0 +1,9 @@
+_build/inc/esp_a2dp_api.inc:26: 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]
+  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).