From 302a43562d3614072536129402a6b8974733793e 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 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 880c5135c..543d18dd1 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)