Merge branch 'docs/make_EN_CN_line_number_consistent' into 'master'

Docs/make en cn line number consistent

Closes DOC-2695

See merge request espressif/esp-idf!17123

docs/en/about.rst

@@ -29,13 +29,11 @@ About
 
     The {IDF_TARGET_NAME} is a 2.4 GHz Wi-Fi Bluetooth Low Energy combo SoC, which integrates a 32-bit RISC-V RV32IMC single-core processor.
 
-
 .. figure:: ../_static/about-doc.png
     :align: center
     :alt: Espressif IoT Integrated Development Framework
     :figclass: align-center
 
     Espressif IoT Integrated Development Framework
 
-The ESP-IDF, Espressif IoT Development Framework, provides toolchain, API, components and workflows to develop applications for {IDF_TARGET_NAME} using Windows, Linux and Mac OS operating systems.
-
+The ESP-IDF, Espressif IoT Development Framework, provides toolchain, API, components and workflows to develop applications for {IDF_TARGET_NAME} using Windows, Linux and macOS operating systems.

docs/en/api-guides/build-system.rst

@@ -31,7 +31,7 @@ Concepts
 
 - "components" are modular pieces of standalone code which are compiled into static libraries (.a files) and linked into an app. Some are provided by ESP-IDF itself, others may be sourced from other places.
 
-- "Target" is the hardware for which an application is built. A full list of supported targets in your version if ESP-IDF can be seen by running `idf.py --list-targets`.
+- "Target" is the hardware for which an application is built. A full list of supported targets in your version of ESP-IDF can be seen by running `idf.py --list-targets`.
 
 Some things are not part of the project:
 
@@ -1060,7 +1060,7 @@ The subproject is inserted as an external project from the top-level project, by
 Selecting the Target
 ====================
 
-ESP-IDF supports multiple targets (chips). A full list of supported targets in your version if ESP-IDF can be seen by running `idf.py --list-targets`.
+ESP-IDF supports multiple targets (chips). A full list of supported targets in your version of ESP-IDF can be seen by running `idf.py --list-targets`.
 
 To select the target before building the project, use ``idf.py set-target <target>`` command, for example::
 

docs/en/api-guides/error-handling.rst

@@ -68,6 +68,7 @@ Error message will typically look like this::
 
 - Finally, backtrace is printed. This is part of panic handler output common to all fatal errors. See :doc:`Fatal Errors <fatal-errors>` for more information about the backtrace.
 
+
 .. _esp-error-check-without-abort-macro:
 
 ``ESP_ERROR_CHECK_WITHOUT_ABORT`` macro
@@ -137,7 +138,11 @@ Some examples::
 Error handling patterns
 -----------------------
 
-1. Attempt to recover. Depending on the situation, this might mean to retry the call after some time, or attempt to de-initialize the driver and re-initialize it again, or fix the error condition using an out-of-band mechanism (e.g reset an external peripheral which is not responding).
+1. Attempt to recover. Depending on the situation, we may try the following methods:
+
+   - retry the call after some time;
+   - attempt to de-initialize the driver and re-initialize it again;
+   - fix the error condition using an out-of-band mechanism (e.g reset an external peripheral which is not responding).
 
    Example::
 
@@ -169,7 +174,7 @@ Error handling patterns
 
 3. Convert into unrecoverable error, for example using ``ESP_ERROR_CHECK``. See `ESP_ERROR_CHECK macro`_ section for details.
 
-   Terminating the application in case of an error is usually undesirable behaviour for middleware components, but is sometimes acceptable at application level.
+   Terminating the application in case of an error is usually undesirable behavior for middleware components, but is sometimes acceptable at application level.
 
    Many ESP-IDF examples use ``ESP_ERROR_CHECK`` to handle errors from various APIs. This is not the best practice for applications, and is done to make example code more concise.
 
@@ -183,9 +188,8 @@ C++ Exceptions
 
 Support for C++ Exceptions in ESP-IDF is disabled by default, but can be enabled using :ref:`CONFIG_COMPILER_CXX_EXCEPTIONS` option.
 
-Enabling exception handling normally increases application binary size by a few kB. Additionally it may be necessary to reserve some amount of RAM for exception emergency pool. Memory from this pool will be used if it is not possible to allocate exception object from the heap. Amount of memory in the emergency pool can be set using :ref:`CONFIG_COMPILER_CXX_EXCEPTIONS_EMG_POOL_SIZE` variable.
+Enabling exception handling normally increases application binary size by a few KB. Additionally it may be necessary to reserve some amount of RAM for exception emergency pool. Memory from this pool will be used if it is not possible to allocate exception object from the heap. Amount of memory in the emergency pool can be set using :ref:`CONFIG_COMPILER_CXX_EXCEPTIONS_EMG_POOL_SIZE` variable.
 
 If an exception is thrown, but there is no ``catch`` block, the program will be terminated by ``abort`` function, and backtrace will be printed. See :doc:`Fatal Errors <fatal-errors>` for more information about backtraces.
 
 See :example:`cxx/exceptions` for an example of C++ exception handling.
-

docs/en/api-guides/esp-ble-mesh/ble-mesh-architecture.rst

@@ -52,6 +52,7 @@ ESP-BLE-MESH architecture includes five key parts:
   - Based on ESP-BLE-MESH protocol stack and ``Mesh Models``.
   - By calling API and handling Event, ``Applications`` interact with ``Mesh Networking`` and ``Mesh Provisioning`` in ESP-BLE-MESH protocol stack, as well as a series of Models provided by ``Mesh Models``.
 
+
 1.1 Mesh Protocol Stack
 -----------------------
 

docs/en/api-guides/jtag-debugging/building-openocd-macos.rst

@@ -25,6 +25,7 @@ Install packages that are required to compile OpenOCD using Homebrew::
 
     brew install automake libtool libusb wget [email protected] pkg-config
 
+
 Build OpenOCD
 =============
 
@@ -47,8 +48,8 @@ Optionally you can add ``sudo make install`` step at the end. Skip it, if you ha
 
 Once ``make`` process is successfully completed, the executable of OpenOCD will be saved in ``~/esp/openocd-esp32/src/openocd`` directory.
 
+
 Next Steps
 ==========
 
 To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-target`.
-

docs/en/api-guides/jtag-debugging/configure-ft2232h-jtag.rst

@@ -2,7 +2,6 @@
    :start-after: devkit-defs
    :end-before: ---
 
-
 Configure |devkit-name| JTAG Interface
 ======================================
 :link_to_translation:`zh_CN:[中文]`
@@ -126,7 +125,6 @@ Manually unloading the driver
 
       Attempting to use serial over the wrong channel with the FTDI driver will cause a kernel panic. The ESP-WROVER-KIT uses channel A for JTAG and channel B for serial.
 
-
 4. Run OpenOCD:
 
    .. include:: {IDF_TARGET_PATH_NAME}.inc

docs/zh_CN/about.rst

@@ -23,7 +23,7 @@
     {IDF_TARGET_NAME} 是一款支持 2.4 GHz Wi-Fi 和低功耗蓝牙的芯片，搭载 Xtensa® 32 位 LX7 处理器。
 
 
-.. only:: esp32c3
+.. only:: esp32c3 or esp32c2
 
     本指南为 {IDF_TARGET_NAME} 官方应用开发框架 `ESP-IDF <https://github.com/espressif/esp-idf>`_ 的配套文档。
 
@@ -37,4 +37,3 @@
     乐鑫物联网综合开发框架
 
 ESP-IDF 即乐鑫物联网开发框架，可为在 Windows、Linux 和 macOS 系统平台上开发 {IDF_TARGET_NAME} 应用程序提供工具链、API、组件和工作流程的支持。
-

docs/zh_CN/api-guides/build-system.rst

@@ -5,7 +5,6 @@
 
 本文档主要介绍 ESP-IDF 构建系统的实现原理以及 ``组件`` 等相关概念。如需您想了解如何组织和构建新的 ESP-IDF 项目或组件，请阅读本文档。
 
-
 概述
 ====
 
@@ -32,7 +31,7 @@ ESP-IDF 可以显式地指定和配置每个组件。在构建项目的时候，
 
 - ``组件`` 是模块化且独立的代码，会被编译成静态库（.a 文件）并链接到应用程序。部分组件由 ESP-IDF 官方提供，其他组件则来源于其它开源项目。
 
-- ``目标`` 特指运行构建后应用程序的硬件设备。ESP-IDF 当前仅支持 ``esp32`` 和 ``esp32s2`` 以及 ``esp32c3`` 这三个硬件目标。
+- ``目标`` 特指运行构建后应用程序的硬件设备。运行 `idf.py --list-targets` 可以查看当前 ESP-IDF 版本中支持目标的完整列表。
 
 请注意，以下内容并不属于项目的组成部分：
 
@@ -193,7 +192,7 @@ idf.py 选项
 设置 Python 解释器
 ------------------
 
-ESP-IDF 适用于所有支持的 Python 版本。即使您系统中默认的 ``python`` 解释器仍是 Python 2.7，ESP-IDF 也可以使用，但建议您升级至 Python 3。
+ESP-IDF 适用于 Python 3.7 以上版本。
 
 ``idf.py`` 和其他的 Python 脚本会使用默认的 Python 解释器运行，如 ``python``。您可以通过 ``python3 $IDF_PATH/tools/idf.py ...`` 命令切换到别的 Python 解释器，或者您可以通过设置 shell 别名或其他脚本来简化该命令。
 
@@ -1061,11 +1060,7 @@ Flash 参数
 选择目标芯片
 ====================
 
-ESP-IDF 支持多款芯片，它们通过在软件中使用不同的 “目标” (target) 名进行区分，具体对应关系如下：
-
-* ``esp32`` — 适用于 ESP32-D0WD、ESP32-D2WD、ESP32-S0WD (ESP-SOLO)、ESP32-U4WDH、ESP32-PICO-D4
-* ``esp32s2``— 适用于 ESP32-S2
-* ``esp32c3``— 适用于 ESP32-C3
+ESP-IDF 支持多款芯片，运行 `idf.py --list-targets` 可以查看当前 ESP-IDF 版本中支持目标的完整列表。
 
 在构建项目前，请首先根据您的芯片选择正确的软件目标，具体命令为 ``idf.py set-target <target>``。举例 ::
 
@@ -1542,13 +1537,19 @@ ESP-IDF 构建系统的列表文件位于 :idf:`/tools/cmake` 中。实现构建
 
 请参考 :idf_file:`/tools/cmake/project.cmake` 获取更多信息。
 
+
 .. _migrating_from_make:
 
 从 ESP-IDF GNU Make 构建系统迁移到 CMake 构建系统
 =================================================
 
 ESP-IDF CMake 构建系统与旧版的 GNU Make 构建系统在某些方面非常相似，开发者都需要提供 include 目录、源文件等。然而，有一个语法上的区别，即对于 ESP-IDF CMake 构建系统，开发者需要将这些作为参数传递给注册命令 ``idf_component_register``。
 
+自动转换工具
+-------------------------
+
+在 ESP-IDF v4.x 版本中，`tools/cmake/convert_to_cmake.py` 提供了项目自动转换工具。由于该脚本依赖于 `make` 构建系统，所以 v5.0 版本中不包含该脚本。
+
 CMake 中不可用的功能
 --------------------
 

docs/zh_CN/api-guides/error-handling.rst

@@ -16,7 +16,7 @@
 
 -  不可恢复（严重）的错误：
 
-   -  断言失败（使用 ``assert`` 宏或者其它类似方法）或者直接调用 ``abort()`` 函数造成的错误
+   -  断言失败（使用 ``assert`` 宏或者其它类似方法，可参考 :ref:`assertions`）或者直接调用 ``abort()`` 函数造成的错误
    -  CPU 异常：访问受保护的内存区域、非法指令等
    -  系统级检查：看门狗超时、缓存访问错误、堆栈溢出、堆栈粉碎、堆栈损坏等
 
@@ -33,6 +33,7 @@ ESP-IDF 中大多数函数会返回 :cpp:type:`esp_err_t` 类型的错误码，
 
 完整错误代码列表，请见 :doc:`错误代码参考 <../api-reference/error-codes>` 中查看完整的错误列表。
 
+
 错误码到错误消息
 ----------------
 
@@ -49,9 +50,7 @@ ESP-IDF 中大多数函数会返回 :cpp:type:`esp_err_t` 类型的错误码，
 
 宏 :cpp:func:`ESP_ERROR_CHECK` 的功能和 ``assert`` 类似，不同之处在于：这个宏会检查 :cpp:type:`esp_err_t` 的值，而非判断 ``bool`` 条件。如果传给 :cpp:func:`ESP_ERROR_CHECK` 的参数不等于 :c:macro:`ESP_OK` ，则会在控制台上打印错误消息，然后调用 ``abort()`` 函数。
 
-错误消息通常如下所示：
-
-.. code:: bash
+错误消息通常如下所示::
 
    ESP_ERROR_CHECK failed: esp_err_t 0x107 (ESP_ERR_TIMEOUT) at 0x400d1fdf
 
@@ -61,13 +60,14 @@ ESP-IDF 中大多数函数会返回 :cpp:type:`esp_err_t` 类型的错误码，
 
    Backtrace: 0x40086e7c:0x3ffb4ff0 0x40087328:0x3ffb5010 0x400d1fdf:0x3ffb5030 0x400d0816:0x3ffb5050
 
+.. note:: 如果使用 :doc:`IDF 监视器 <tools/idf-monitor>`，则最后一行回溯结果中的地址将会被自动解析为相应的文件名和行号。
+
 -  第一行打印错误代码的十六进制表示，及该错误在源代码中的标识符。这个标识符取决于 :ref:`CONFIG_ESP_ERR_TO_NAME_LOOKUP` 选项的设定。最后，第一行还会打印程序中该错误发生的具体位置。
 
 -  下面几行显示了程序中调用 :cpp:func:`ESP_ERROR_CHECK` 宏的具体位置，以及传递给该宏的参数。
 
 -  最后一行打印回溯结果。对于所有不可恢复错误，这里在应急处理程序中打印的内容都是一样的。更多有关回溯结果的详细信息，请参阅 :doc:`不可恢复错误 <fatal-errors>` 。
 
-.. note:: 如果使用 :doc:`IDF monitor <tools/idf-monitor>`, 则最后一行回溯结果中的地址将会被替换为相应的文件名和行号。
 
 .. _esp-error-check-without-abort-macro:
 
@@ -144,9 +144,7 @@ ESP-IDF 中大多数函数会返回 :cpp:type:`esp_err_t` 类型的错误码，
 	- 尝试删除该驱动，然后重新进行“初始化”；
 	- 采用其他带外机制，修改导致错误发生的条件（例如，对一直没有响应的外设进行复位等）。
 
-   示例：
-
-   .. code:: c
+   示例::
 
       esp_err_t err;
       do {
@@ -159,9 +157,7 @@ ESP-IDF 中大多数函数会返回 :cpp:type:`esp_err_t` 类型的错误码，
 
 2. 将错误传递回调用程序。在某些中间件组件中，采用此类处理模式代表函数必须以相同的错误码退出，这样才能确保所有分配的资源都能得到释放。
 
-   示例：
-
-   .. code:: c
+   示例::
 
       sdmmc_card_t* card = calloc(1, sizeof(sdmmc_card_t));
       if (card == NULL) {
@@ -179,11 +175,10 @@ ESP-IDF 中大多数函数会返回 :cpp:type:`esp_err_t` 类型的错误码，
 3. 转为不可恢复错误，比如使用 ``ESP_ERROR_CHECK``。详情请见 `ESP_ERROR_CHECK 宏 <#esp-error-check-macro>`_ 章节。
 
    对于中间件组件而言，通常并不希望在发生错误时中止应用程序。不过，有时在应用程序级别，这种做法是可以接受的。
-   在 ESP-IDF 的示例代码中，很多都会使用 ``ESP_ERROR_CHECK`` 来处理各种 API 引发的错误，虽然这不是应用程序的最佳做法，但可以让示例代码看起来更加简洁。
 
-   示例：
+   在 ESP-IDF 的示例代码中，很多都会使用 ``ESP_ERROR_CHECK`` 来处理各种 API 引发的错误，虽然这不是应用程序的最佳做法，但可以让示例代码看起来更加简洁。
 
-   .. code:: c
+   示例::
 
       ESP_ERROR_CHECK(spi_bus_initialize(host, bus_config, dma_chan));
 
@@ -193,6 +188,8 @@ C++ 异常
 
 默认情况下，ESP-IDF 会禁用对 C++ 异常的支持，但是可以通过 :ref:`CONFIG_COMPILER_CXX_EXCEPTIONS` 选项启用。
 
-通常情况下，启用异常处理会让应用程序的二进制文件增加几 kB。此外，启用该功能时还应为异常事故池预留一定内存。当应用程序无法从堆中分配异常对象时，就可以使用这个池中的内存。该内存池的大小可以通过 :ref:`CONFIG_COMPILER_CXX_EXCEPTIONS_EMG_POOL_SIZE` 来设定。
+通常情况下，启用异常处理会让应用程序的二进制文件增加几 KB。此外，启用该功能时还应为异常事故池预留一定内存。当应用程序无法从堆中分配异常对象时，就可以使用这个池中的内存。该内存池的大小可以通过 :ref:`CONFIG_COMPILER_CXX_EXCEPTIONS_EMG_POOL_SIZE` 来设定。
 
 如果 C++ 程序抛出了异常，但是程序中并没有 ``catch`` 代码块来捕获该异常，那么程序的运行就会被 ``abort`` 函数中止，然后打印回溯信息。有关回溯的更多信息，请参阅 :doc:`不可恢复错误 <fatal-errors>` 。
+
+C++ 异常处理示例，请参考 :example:`cxx/exceptions`。