docs: translate idf.py debug target

docs/en/api-guides/jtag-debugging/esp32.inc

@@ -88,11 +88,11 @@
     * - Name
       - Description
     * - ``board/esp32-wrover-kit-3.3v.cfg``
-      - ESP-WROVER-KIT with a 3.3 V ESP32-WROOM-32 module or ESP32-WROVER-B / ESP32-WROVER-E module.
+      - Board configuration file for ESP-WROVER-KIT with a 3.3 V ESP32-WROOM-32 module or ESP32-WROVER-B / ESP32-WROVER-E module.
     * - ``board/esp32-wrover-kit-1.8v.cfg``
-      - ESP-WROVER-KIT with an 1.8 V ESP32-WROVER module.
+      - Board configuration file for ESP-WROVER-KIT with an 1.8 V ESP32-WROVER module.
     * - ``board/esp32-ethernet-kit-3.3v.cfg``
-      - ESP-Ethernet-KIT with a 3.3 V ESP32-WROVER-B / ESP32-WROVER-E module.
+      - Board configuration file for ESP-Ethernet-KIT with a 3.3 V ESP32-WROVER-B / ESP32-WROVER-E module.
     * - ``target/esp32.cfg``
       - ESP32 target configuration file. Can be used together with one of the ``interface/`` configuration files.
     * - ``target/esp32-solo-1.cfg``

docs/en/api-guides/jtag-debugging/esp32s2.inc

@@ -80,7 +80,7 @@
 
 .. openocd-cfg-files
 
-.. list-table:: OpenOCD configuration files for ESP32
+.. list-table:: OpenOCD configuration files for ESP32-S2
     :widths: 25 75
     :header-rows: 1
 

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

@@ -16,11 +16,11 @@
     :start-after: devkit-hw-config
     :end-before: ---
 
-2.  检查 {IDF_TARGET_NAME} 上用于 JTAG 通信的引脚是否被接到了其它硬件上，这可能会影响 JTAG 的工作。
+* 检查 {IDF_TARGET_NAME} 上用于 JTAG 通信的引脚是否被接到了其它硬件上，这可能会影响 JTAG 的工作。
 
-.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
-    :start-after: jtag-pins
-    :end-before: ---
+    .. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
+        :start-after: jtag-pins
+        :end-before: ---
 
 配置 USB 驱动
 ^^^^^^^^^^^^^
@@ -118,7 +118,9 @@ MacOS
 
 4. 运行 OpenOCD::
 
-    openocd -f board/esp32-wrover-kit-3.3v.cfg
+    .. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
+        :start-after: run-openocd
+        :end-before: ---
 
 5. 在另一个终端窗口，再一次加载 FTDI 串口驱动::
 

docs/zh_CN/api-guides/jtag-debugging/esp32.inc

@@ -14,7 +14,7 @@
 
     openocd -f board/esp32-wrover-kit-3.3v.cfg
 
-.. |run-openocd-device-name| replace:: ESP32-WROOM-32 模组的 ESP-WROVER-KIT 开发板
+.. |run-openocd-device-name| replace:: 板载 ESP32-WROOM-32 模组的 ESP-WROVER-KIT 开发板
 
 ---
 
@@ -81,39 +81,39 @@
 
 .. openocd-cfg-files
 
-.. list-table:: OpenOCD configuration files for ESP32
+.. list-table:: ESP32 相关的 OpenOCD 配置文件
     :widths: 25 75
     :header-rows: 1
 
-    * - Name
-      - Description
+    * - 名字
+      - 描述
     * - ``board/esp32-wrover-kit-3.3v.cfg``
-      - ESP-WROVER-KIT with a 3.3 V ESP32-WROOM-32 module or ESP32-WROVER-B / ESP32-WROVER-E module.
+      - 板载 3.3V 模组（ESP32-WROOM-32，ESP32-WROVER-B，ESP32-WROVER-E）的 ESP-WROVER-KIT 开发板配置文件
     * - ``board/esp32-wrover-kit-1.8v.cfg``
-      - ESP-WROVER-KIT with an 1.8 V ESP32-WROVER module.
+      - 板载 1.8V 模组（ESP32-WROVER）的 ESP-WROVER-KIT 开发板配置文件
     * - ``board/esp32-ethernet-kit-3.3v.cfg``
-      - ESP-Ethernet-KIT with a 3.3 V ESP32-WROVER-B / ESP32-WROVER-E module.
+      - 板载 3.3V 模组（ESP32-WROVER-B / ESP32-WROVER-E）的 ESP-Ethernet-KIT 开发板配置文件
     * - ``target/esp32.cfg``
-      - ESP32 target configuration file. Can be used together with one of the ``interface/`` configuration files.
+      - ESP32 的目标配置文件，可以和某个 ``interface/`` 下的配置文件一同使用
     * - ``target/esp32-solo-1.cfg``
-      - Target configuration file for ESP32-SOLO-1 module. Different from ``esp32.cfg`` in that it only configures one CPU.
+      - ESP32-SOLO-1 的目标配置文件，和 ``esp32.cfg`` 的差别在于它仅配置一个 CPU
     * - ``interface/ftdi/esp32_devkitj_v1.cfg``
-      - JTAG adapter configuration file for ESP-WROVER-KIT and ESP-Prog boards.
+      - 适用于 ESP-WROVER-KIT 和 ESP-Prog 板子的 JTAG 适配器配置文件
 
 ---
 
 .. openocd-target-specific-config-vars
 
-.. list-table:: ESP32-specific OpenOCD variables
+.. list-table:: ESP32 相关的 OpenOCD 变量
     :widths: 25 75
     :header-rows: 1
 
-    * - Name
-      - Description
+    * - 名字
+      - 描述
     * - ``ESP32_FLASH_VOLTAGE``
-      - When using 1.8 V flash ESP32 based modules, set this variable to ``1.8``. Refer to :ref:`jtag-debugging-tip-code-flash-voltage`.
+      - 如果 ESP32 模组集成的是 1.8 V 的 Flash，将该变量设置为 ``1.8``，详情请参考 :ref:`jtag-debugging-tip-code-flash-voltage`
     * - ``ESP32_ONLYCPU``
-      - For multi-core targets, can be set to ``1`` to only enable single core debugging.
+      - 对于多核芯片，将该值设置为 ``1`` 可以仅启用单核调试功能
 
 ---
 

docs/zh_CN/api-guides/jtag-debugging/esp32s2.inc

@@ -80,20 +80,20 @@
 
 .. openocd-cfg-files
 
-.. list-table:: OpenOCD configuration files for ESP32
+.. list-table:: ESP32-S2 相关的 OpenOCD 配置文件
     :widths: 25 75
     :header-rows: 1
 
-    * - Name
-      - Description
+    * - 名字
+      - 描述
     * - ``board/esp32s2-kaluga-1.cfg``
-      - Board configuration file for ESP32-S2-Kaluga-1, includes target and adapter configuration.
+      - ESP32-S2-Kaluga-1 开发板配置文件，内部已包含 ESP32-S2 目标配置和 JTAG 适配器配置
     * - ``target/esp32s2.cfg``
-      - ESP32-S2 target configuration file. Can be used together with one of the ``interface/`` configuration files.
+      - ESP32-S2 目标配置文件，可以和某个 ``interface/`` 下的配置文件一同使用
     * - ``interface/ftdi/esp32s2_kaluga_v1.cfg``
-      - JTAG adapter configuration file for ESP32-S2-Kaluga-1 board.
+      - 适用于 ESP32-S2-Kaluga-1 开发板的 JTAG 适配器配置文件
     * - ``interface/ftdi/esp32_devkitj_v1.cfg``
-      - JTAG adapter configuration file for ESP-Prog boards.
+      - 适用于 ESP-Prog 板子的 JTAG 适配器配置文件
 
 ---
 
@@ -155,6 +155,6 @@
 
 .. devkit-hw-config
 
-* *开箱即用，ESP32-S2-Kaluga-1 不需要任何其他硬件配置即可进行 JTAG 调试。 但是，如果遇到问题，请检查 “JTAG” DIP 开关块的开关 2-5 是否在 “ON” 位置。
+* 开箱即用，ESP32-S2-Kaluga-1 不需要任何其他硬件配置即可进行 JTAG 调试。 但是，如果遇到问题，请检查 “JTAG” DIP 开关的 2～5 号是否在 “ON” 的位置。
 
 ---

docs/zh_CN/api-guides/jtag-debugging/index.rst

@@ -45,7 +45,7 @@ JTAG 调试
 本文将指导如何在 Linux，Windows 和 MacOS 环境下为 {IDF_TARGET_NAME} 安装 OpenOCD，并使用 GDB 进行软件调试。除了个别操作系统的安装过程有所差别以外，软件用户界面和使用流程都是一样的。
 
 .. note::
-    本文使用的图片素材来自于 Ubuntu 16.04 LTE 上 Eclipse Neon 3 软件的截图，不同的操作系统（Windows， MacOS 或者 Linux）和 Eclipse 软件版本在用户界面上可能会有细微的差别。
+    本文使用的图片素材来自于 Ubuntu 16.04 LTS 上 Eclipse Neon 3 软件的截图，不同的操作系统（Windows， MacOS 或者 Linux）和 Eclipse 软件版本在用户界面上可能会有细微的差别。
 
 .. _jtag-debugging-how-it-works:
 
@@ -148,13 +148,13 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G
 
 打开终端，按照快速入门中的指南 :ref:`设置好开发环境 <get-started-set-up-env>` ，然后运行如下命令，启动 OpenOCD（该命令在 Windows，Linux，和 macOS 中通用）:
 
-    .. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
+.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
     :start-after: run-openocd
     :end-before: ---
 
 .. note::
 
-    上述命令中 ``-f`` 选项后跟的配置文件专用于板载 |run-openocd-device-name|。您可能需要根据具体使用的硬件而选择或修改不同的配置文件，相关指导请参阅 :ref:`jtag-debugging-tip-openocd-configure-target`。
+    上述命令中 ``-f`` 选项后跟的配置文件专用于 |run-openocd-device-name|。您可能需要根据具体使用的硬件而选择或修改不同的配置文件，相关指导请参阅 :ref:`jtag-debugging-tip-openocd-configure-target`。
 
 .. highlight:: none
 

docs/zh_CN/api-guides/jtag-debugging/using-debugger.rst

@@ -188,3 +188,47 @@
 注意上面日志的倒数第三行显示了调试器已经在 ``app_main()`` 函数的断点处停止，该断点在 ``gdbinit`` 文件中设定。由于处理器已经暂停运行，LED 也不会闪烁。如果这也是你看到的现象，你可以开始调试了。
 
 如果你不太了解 GDB 的常用方法，请查阅 :ref:`jtag-debugging-examples-command-line` 文章中的调试示例章节 :ref:`jtag-debugging-examples`。
+
+
+.. _jtag-debugging-with-idf-py:
+
+使用 idf.py 进行调试
+^^^^^^^^^^^^^^^^^^^^
+
+我们还可以使用 ``idf.py`` 更方便地执行上述提到的调试命令：
+
+1.  ``idf.py openocd``
+
+    在终端中运行 OpenOCD，其配置信息来源于环境变量或者命令行。默认会使用 ``OPENOCD_SCRIPTS`` 环境变量中指定的脚本路径，它是由 ESP-IDF 项目仓库中的导出脚本（``export.sh`` or ``export.bat``）添加到系统环境变量中的。
+    当然，我们可以在命令行中通过  ``--openocd-scripts`` 来覆盖这个变量的值。
+
+    .. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
+        :start-after: idf-py-openocd-default-cfg
+        :end-before: ---
+
+    你可以定义 ``OPENOCD_COMMANDS`` 环境变量来指定当前开发板的 JTAG 配置，或者通过 ``--openocd-commands`` 传递该参数。如果这两者都没有被定义，那么 OpenOCD 会使用 |idf-py-def-cfg| 参数来启动。
+
+
+2.  ``idf.py gdb``
+
+    根据当前项目的 elf 文件自动生成 gdb 启动脚本， 然后会按照 :ref:`jtag-debugging-using-debugger-command-line` 中所描述的步骤启动 GDB。
+
+
+3.  ``idf.py gdbtui``
+
+    和步骤 2 相同，但是会在启动 GDB 的时候传递 ``tui`` 参数，这样可以方便在调试过程中查看源代码。
+
+
+4.  ``idf.py gdbgui``
+
+    启动 `gdbgui <https://www.gdbgui.com>`_，在浏览器中打开调试器的前端界面。
+
+
+    上述这些命令也可以合并到一起使用，``idf.py`` 会自动将后台进程（比如 openocd）最先运行，交互式进程（比图 gdb， monitor）最后运行。
+
+    常用的组合命令如下所示::
+
+        idf.py openocd gdbgui monitor
+
+
+    上述命令会将 OpenOCD 运行至后台，然后启动 `gdbgui <https://www.gdbgui.com>`_ 打开一个浏览器窗口，显示调试器的前端界面，最后在活动终端打开串口监视器。