docs: fix check_docs not working for multiple builders

When building docs with multiple builders the warning logs are now checked after
each run. Solves the issue where the logs would be overwritten by next builder before checking.

Closes IDF-1659

docs/build_docs.py

@@ -238,33 +238,24 @@ def action_build(args):
         if ret != 0:
             return ret
 
-    # check Doxygen warnings:
-    ret = 0
-    for target in targets:
-        for language in languages:
-            build_dir = os.path.realpath(os.path.join(args.build_dir, language, target))
-            ret += check_docs(language, target,
-                              log_file=os.path.join(build_dir, DXG_WARN_LOG),
-                              known_warnings_file=DXG_KNOWN_WARNINGS,
-                              out_sanitized_log_file=os.path.join(build_dir, DXG_SANITIZED_LOG))
-
-    # check Sphinx warnings:
-    for target in targets:
-        for language in languages:
-            build_dir = os.path.realpath(os.path.join(args.build_dir, language, target))
-            ret += check_docs(language, target,
-                              log_file=os.path.join(build_dir, SPHINX_WARN_LOG),
-                              known_warnings_file=SPHINX_KNOWN_WARNINGS,
-                              out_sanitized_log_file=os.path.join(build_dir, SPHINX_SANITIZED_LOG))
-
-    if ret != 0:
-        return ret
-
 
 def call_build_docs(entry):
     (language, target, build_dir, sphinx_parallel_jobs, builders, input_docs) = entry
     for buildername in builders:
         ret = sphinx_call(language, target, build_dir, sphinx_parallel_jobs, buildername, input_docs)
+
+        # Warnings are checked after each builder as logs are overwritten
+        # check Doxygen warnings:
+        ret += check_docs(language, target,
+                          log_file=os.path.join(build_dir, DXG_WARN_LOG),
+                          known_warnings_file=DXG_KNOWN_WARNINGS,
+                          out_sanitized_log_file=os.path.join(build_dir, DXG_SANITIZED_LOG))
+        # check Sphinx warnings:
+        ret += check_docs(language, target,
+                          log_file=os.path.join(build_dir, SPHINX_WARN_LOG),
+                          known_warnings_file=SPHINX_KNOWN_WARNINGS,
+                          out_sanitized_log_file=os.path.join(build_dir, SPHINX_SANITIZED_LOG))
+
         if ret != 0:
             return ret
 

docs/conf_common.py

@@ -125,7 +125,7 @@ print('Version: {0}  Release: {1}'.format(version, release))
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['**/inc/**', '_static', '**/_build']
+exclude_patterns = ['**/inc/**', '_static/', '_build/**']
 
 
 BT_DOCS = ['api-guides/blufi.rst',

docs/en/contribute/documenting-code.rst

@@ -263,7 +263,7 @@ Define identifiers from 'sdkconfig.h', generated by the default menuconfig setti
 
 * CONFIG_FREERTOS_UNICORE
 
-Define identifiers from the soc '*_caps' headers, e.g:
+Define identifiers from the soc '\*_caps' headers, e.g:
 
 * SOC_BT_SUPPORTED
 * SOC_CAN_SUPPORTED

docs/en/hw-reference/esp32s2/user-guide-esp-lyrap-lcd32-v1.1.rst

@@ -10,7 +10,9 @@ The ESP-LyraP-LCD32 extends the functionality of your main board by adding an LC
 
 .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp-lyrap-lcd32-v1.1-3d.png
     :align: center
-    :scale: 90%
+    :width: 2243px
+    :height: 1534px
+    :scale: 30%
     :alt: ESP-LyraP-LCD32
     :figclass: align-center
 
@@ -35,7 +37,9 @@ Description of Components
 
 .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp-lyrap-lcd32-v1.1-layout-front.png
     :align: center
-    :scale: 90%
+    :width: 934px
+    :height: 600px
+    :scale: 70%
     :alt: ESP-LyraP-LCD32 - front
     :figclass: align-center
 

docs/en/hw-reference/esp32s2/user-guide-esp-lyrat-8311a_v1.2.rst

@@ -16,7 +16,9 @@ This extension board can be used in many ways. The applications might include vo
 
 .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp-lyrat-8311a-v1.2-3d.png
     :align: center
-    :scale: 90%
+    :width: 2545px
+    :height: 1786px
+    :scale: 30%
     :alt: ESP-LyraT-8311A
     :figclass: align-center
 
@@ -41,7 +43,9 @@ Description of Components
 
 .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp-lyrat-8311a-v1.2-layout-front.png
     :align: center
-    :scale: 90%
+    :width: 934px
+    :height: 565px
+    :scale: 80%
     :alt: ESP-LyraT-8311A - front
     :figclass: align-center
 

docs/en/hw-reference/esp32s2/user-guide-esp32-s2-kaluga-1-kit.rst

@@ -19,7 +19,9 @@ There are many ways of how the ESP32-S2's abundant functionalities can be used.
 
 .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-s2-kaluga-1-kit-v1.0-3d.png
     :align: center
-    :scale: 90%
+    :width: 3452px
+    :height: 1590px
+    :scale: 20%
     :alt: ESP32-S2-Kaluga-1-Kit-Assembly
     :figclass: align-center
 
@@ -68,7 +70,9 @@ The ESP32-S2-Kaluga-1 board has connectors for:
 
 .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-s2-kaluga-1-v1.2-3d.png
     :align: center
-    :scale: 90%
+    :width: 2631px
+    :height: 1966px
+    :scale: 25%
     :alt: ESP32-S2-Kaluga-1
     :figclass: align-center
 
@@ -81,14 +85,14 @@ All the four extension boards are specially desgined to support the following fe
     * Supports acrylic panels up to 5 mm
     * Wet hand operation
     * Water rejection, ESP32-S2 can be configured to disable all touchpads automatically if multiple pads are simultaneously covered with water and to re-enable touchpads if the water is removed
- 
+
 * Audio playback
     * Connect speakers to play audio
     * Use together with the Touch panel to control audio playback and adjust volume
- 
+
 * LCD display
     * LCD interface (8-bit parallel RGB, 8080, and 6800 interface)
- 
+
 * Camera image acquisition
     * Supports OV2640 and OV3660 camera modules
     * 8-bit DVP image sensor interface (ESP32-S2 also supports 16-bit DVP image sensors, you can design it yourself)
@@ -101,7 +105,9 @@ Description of Components
 
 .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-s2-kaluga-1-v1.2-layout-front.png
     :align: center
-    :scale: 90%
+    :width: 934px
+    :height: 645px
+    :scale: 70%
     :alt: ESP32-S2-Kaluga-1 - front
     :figclass: align-center
 

docs/sphinx-known-warnings.txt

@@ -6,23 +6,6 @@
 #
 # 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
-#
-# Note: warnings below will be gone after upgrade
-#       to the following package==version
-#
-#       sphinx==1.8.4
-#       breathe==4.11.1
-#
-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
-  ---------------------^
-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
-  ---------------------^
-
 #
 # Breathe known issue: https://github.com/michaeljones/breathe/issues/405
 # Sphinx known issue: https://github.com/sphinx-doc/sphinx/pull/5901

docs/zh_CN/api-guides/external-ram.rst

@@ -124,5 +124,5 @@ ESP-IDF 启动过程中，片外 RAM 被映射到以 0x3F800000 起始的数据
    .. include:: inc/external-ram-esp32-notes.rst
 
 .. _ESP32 ECO: https://www.espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf
-
+.. _ESP32 ECO V3 User Guide: https://www.espressif.com/sites/default/files/documentation/ESP32_ECO_V3_User_Guide__EN.pdf
 

docs/zh_CN/hw-reference/esp32s2/user-guide-esp-lyrap-lcd32-v1.1.rst

@@ -10,7 +10,9 @@ ESP-LyraP-LCD32 可为您的主板增加 LCD 图像显示功能。
 
 .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp-lyrap-lcd32-v1.1-3d.png
     :align: center
-    :scale: 90%
+    :width: 2243px
+    :height: 1534px
+    :scale: 30%
     :alt: ESP-LyraP-LCD32
     :figclass: align-center
 
@@ -35,14 +37,16 @@ ESP-LyraP-LCD32 可为您的主板增加了一块 3.2" LCD 图形显示屏（320
 
 .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp-lyrap-lcd32-v1.1-layout-front.png
     :align: center
-    :scale: 90%
+    :width: 934px
+    :height: 600px
+    :scale: 70%
     :alt: ESP-LyraP-LCD32 - 正面
     :figclass: align-center
 
     ESP-LyraP-LCD32 - front （点击放大）
 
 
-在下面的组件描述中，**保留**表示该功能可用，但当前版本的套件并未启用该功能。
+在下面的组件描述中，**保留** 表示该功能可用，但当前版本的套件并未启用该功能。
 
 
 .. list-table::

docs/zh_CN/hw-reference/esp32s2/user-guide-esp-lyrat-8311a_v1.2.rst

@@ -16,7 +16,9 @@ ESP-LyraT-8311A 扩展板有多种使用方式。该应用程序包括语音用
 
 .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp-lyrat-8311a-v1.2-3d.png
     :align: center
-    :scale: 90%
+    :width: 2545px
+    :height: 1786px
+    :scale: 30%
     :alt: ESP-LyraT-8311A
     :figclass: align-center
 
@@ -41,7 +43,9 @@ ESP-LyraT-8311A 主要用于音频应用，但也可根据实际需求用作它
 
 .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp-lyrat-8311a-v1.2-layout-front.png
     :align: center
-    :scale: 90%
+    :width: 934px
+    :height: 565px
+    :scale: 80%
     :alt: ESP-LyraT-8311A - 正面
     :figclass: align-center
 
@@ -49,7 +53,7 @@ ESP-LyraT-8311A 主要用于音频应用，但也可根据实际需求用作它
 
 下表将从图片右上角开始，以顺时针顺序介绍上图中的主要组件。
 
-**保留**表示该功能可用，但当前版本的套件并未启用该功能。
+**保留** 表示该功能可用，但当前版本的套件并未启用该功能。
 
 
 .. list-table::

docs/zh_CN/hw-reference/esp32s2/user-guide-esp32-s2-kaluga-1-kit.rst

@@ -1,6 +1,6 @@
-=====================
+=======================
 ESP32-S2-Kaluga-1 套件
-=====================
+=======================
 
 :link_to_translation:`en:[English]`
 
@@ -19,7 +19,9 @@ ESP32-S2 的功能强大，应用场景非常丰富。对于初学者来说，
 
 .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-s2-kaluga-1-kit-v1.0-3d.png
     :align: center
-    :scale: 90%
+    :width: 3452px
+    :height: 1590px
+    :scale: 20%
     :alt: ESP32-S2-Kaluga-1 套装装配图
     :figclass: align-center
 
@@ -68,7 +70,9 @@ ESP32-S2-Kaluga-1 主板配备了多个连接器，可连接至以下扩展板
 
 .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-s2-kaluga-1-v1.2-3d.png
     :align: center
-    :scale: 90%
+    :width: 2631px
+    :height: 1966px
+    :scale: 25%
     :alt: ESP32-S2-Kaluga-1
     :figclass: align-center
 
@@ -101,10 +105,12 @@ ESP32-S2-Kaluga-1 主板配备了多个连接器，可连接至以下扩展板
 
 .. figure:: https://dl.espressif.com/dl/schematics/pictures/esp32-s2-kaluga-1-v1.2-layout-front.png
     :align: center
-    :scale: 90%
+    :width: 934px
+    :height: 645px
+    :scale: 70%
     :alt: ESP32-S2-Kaluga-1 - 正面
     :figclass: align-center
-    
+
     ESP32-S2-Kaluga-1 - 正面（点击放大）
 
 
@@ -141,7 +147,7 @@ ESP32-S2-Kaluga-1 主板配备了多个连接器，可连接至以下扩展板
       - 按下 **Boot** 键并保持，同时按一下 **Reset** 键，进入“固件下载”模式，通过串口下载固件。
     * - USB-UART/JTAG 端口
       - PC 和 ESP32-S2 模组之间的通信接口（UART 或 JTAG）
-    * - USB 电源端口 
+    * - USB 电源端口
       - 电路板的电源
     * - 电池端口
       - 2 针连接器，连接外部电源
@@ -224,7 +230,7 @@ ESP32-S2-Kaluga-1 上电前，请首先确认开发板完好无损。
     - 螺丝 (x 4)
     - 螺母 (x 4)
 
-零售购买，请前往 https://www.espressif.com/zh-hans/company/contact/buy-a-sample。 
+零售购买，请前往 https://www.espressif.com/zh-hans/company/contact/buy-a-sample。
 
 
 批发订单
@@ -232,7 +238,7 @@ ESP32-S2-Kaluga-1 上电前，请首先确认开发板完好无损。
 
 ESP32-S2-Kaluga-1 开发套件的批发包装为纸板箱。
 
-批量订货，请参考 `乐鑫产品订购信息 <https://www.espressif.com/sites/default/files/documentation/espressif_products_ordering_information_cn.pdf>`__ (PDF)。
+批量订货，请参考 `乐鑫产品订购信息 <https://www.espressif.com/sites/default/files/documentation/espressif_products_ordering_information_cn.pdf>`_ (PDF)。
 
 
 硬件参考
@@ -281,7 +287,7 @@ ESP32-S2-Kaluga-1 的主要组件和连接方式如下图所示。
     user-guide-esp-lyrat-8311a_v1.2
 
 - `ESP32-S2-WROVER 技术规格书 <https://www.espressif.com/sites/default/files/documentation/esp32-s2-wrover_esp32-s2-wrover-i_datasheet_cn.pdf>`_ (PDF)
-- `《乐鑫产品订购信息》<https://www.espressif.com/sites/default/files/documentation/espressif_products_ordering_information_cn.pdf>`_ (PDF)
+- `乐鑫产品订购信息 <https://www.espressif.com/sites/default/files/documentation/espressif_products_ordering_information_cn.pdf>`_ (PDF)
 
 - `ESP32-S2-Kaluga-1 原理图 <https://dl.espressif.com/dl/schematics/ESP32-S2-Kaluga-1_V1_2_SCH_20200424A.pdf>`_ (PDF)
 - `ESP32-S2-Kaluga-1 PCB 布局图 <https://dl.espressif.com/dl/schematics/ESP32-S2-Kaluga-1_V1_2_PCB_20200325AF.pdf>`_ (PDF)