From 67ea59d6052d0f672e53496b354f9cd577693d02 Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Fri, 29 May 2020 20:10:18 +0800 Subject: [PATCH] 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 | 35 +++++++------------ docs/conf_common.py | 2 +- docs/en/contribute/documenting-code.rst | 2 +- .../user-guide-esp-lyrap-lcd32-v1.1.rst | 8 +++-- .../user-guide-esp-lyrat-8311a_v1.2.rst | 8 +++-- .../user-guide-esp32-s2-kaluga-1-kit.rst | 18 ++++++---- docs/sphinx-known-warnings.txt | 17 --------- docs/zh_CN/api-guides/external-ram.rst | 2 +- .../user-guide-esp-lyrap-lcd32-v1.1.rst | 10 ++++-- .../user-guide-esp-lyrat-8311a_v1.2.rst | 10 ++++-- .../user-guide-esp32-s2-kaluga-1-kit.rst | 26 ++++++++------ 11 files changed, 70 insertions(+), 68 deletions(-) diff --git a/docs/build_docs.py b/docs/build_docs.py index f6e0e6515..2a449ae38 100755 --- a/docs/build_docs.py +++ b/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 diff --git a/docs/conf_common.py b/docs/conf_common.py index 9c84eefc0..beaf6ad2e 100644 --- a/docs/conf_common.py +++ b/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', diff --git a/docs/en/contribute/documenting-code.rst b/docs/en/contribute/documenting-code.rst index 896b1f963..b6e9dd1d0 100644 --- a/docs/en/contribute/documenting-code.rst +++ b/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 diff --git a/docs/en/hw-reference/esp32s2/user-guide-esp-lyrap-lcd32-v1.1.rst b/docs/en/hw-reference/esp32s2/user-guide-esp-lyrap-lcd32-v1.1.rst index 4c8b51b52..2443b2a62 100644 --- a/docs/en/hw-reference/esp32s2/user-guide-esp-lyrap-lcd32-v1.1.rst +++ b/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 diff --git a/docs/en/hw-reference/esp32s2/user-guide-esp-lyrat-8311a_v1.2.rst b/docs/en/hw-reference/esp32s2/user-guide-esp-lyrat-8311a_v1.2.rst index 820fb670b..74f328678 100644 --- a/docs/en/hw-reference/esp32s2/user-guide-esp-lyrat-8311a_v1.2.rst +++ b/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 diff --git a/docs/en/hw-reference/esp32s2/user-guide-esp32-s2-kaluga-1-kit.rst b/docs/en/hw-reference/esp32s2/user-guide-esp32-s2-kaluga-1-kit.rst index 48057f209..d2b799ca2 100644 --- a/docs/en/hw-reference/esp32s2/user-guide-esp32-s2-kaluga-1-kit.rst +++ b/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 diff --git a/docs/sphinx-known-warnings.txt b/docs/sphinx-known-warnings.txt index 89e5f4943..390672826 100644 --- a/docs/sphinx-known-warnings.txt +++ b/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 diff --git a/docs/zh_CN/api-guides/external-ram.rst b/docs/zh_CN/api-guides/external-ram.rst index 1e9da6276..3e6e49b79 100644 --- a/docs/zh_CN/api-guides/external-ram.rst +++ b/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 diff --git a/docs/zh_CN/hw-reference/esp32s2/user-guide-esp-lyrap-lcd32-v1.1.rst b/docs/zh_CN/hw-reference/esp32s2/user-guide-esp-lyrap-lcd32-v1.1.rst index 2bb037613..52c20411b 100644 --- a/docs/zh_CN/hw-reference/esp32s2/user-guide-esp-lyrap-lcd32-v1.1.rst +++ b/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:: diff --git a/docs/zh_CN/hw-reference/esp32s2/user-guide-esp-lyrat-8311a_v1.2.rst b/docs/zh_CN/hw-reference/esp32s2/user-guide-esp-lyrat-8311a_v1.2.rst index 958b26df3..27aae03c6 100644 --- a/docs/zh_CN/hw-reference/esp32s2/user-guide-esp-lyrat-8311a_v1.2.rst +++ b/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:: diff --git a/docs/zh_CN/hw-reference/esp32s2/user-guide-esp32-s2-kaluga-1-kit.rst b/docs/zh_CN/hw-reference/esp32s2/user-guide-esp32-s2-kaluga-1-kit.rst index 99cd3847e..e7cef7c22 100644 --- a/docs/zh_CN/hw-reference/esp32s2/user-guide-esp32-s2-kaluga-1-kit.rst +++ b/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 开发套件的批发包装为纸板箱。 -批量订货,请参考 `乐鑫产品订购信息 `__ (PDF)。 +批量订货,请参考 `乐鑫产品订购信息 `_ (PDF)。 硬件参考 @@ -281,7 +287,7 @@ ESP32-S2-Kaluga-1 的主要组件和连接方式如下图所示。 user-guide-esp-lyrat-8311a_v1.2 - `ESP32-S2-WROVER 技术规格书 `_ (PDF) -- `《乐鑫产品订购信息》`_ (PDF) +- `乐鑫产品订购信息 `_ (PDF) - `ESP32-S2-Kaluga-1 原理图 `_ (PDF) - `ESP32-S2-Kaluga-1 PCB 布局图 `_ (PDF)