Merge pull request #1648 from espressif/docs/translate_coverage

docs: Provide CN translation for coverage.rst

Author: Shen7436

docs_espressif/en/additionalfeatures/coverage.rst

@@ -1,79 +1,86 @@
-ESP-IDF Coverage
-===============================
+Code Coverage
+=============
 
-Source code coverage is data indicating the count and frequency of every program execution path that has been taken within a program runtime. `GCOV <https://en.wikipedia.org/wiki/Gcov>`_ is a GCC tool that, when used in concert with the compiler, can generate log files indicating the execution count of each line of a source code.
+:link_to_translation:`zh_CN:[中文]`
+
+Source code coverage provides data indicating the count and frequency of every program execution path taken during runtime. `GCOV <https://en.wikipedia.org/wiki/Gcov>`_ is a GCC tool that, when used with the compiler, generates log files showing the execution count of each line of source code.
 
 Your ESP-IDF project should be configured to generate ``gcda/gcno`` coverage files using ``gcov``. Please read `GCOV Code Coverage <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/app_trace.html#gcov-source-code-coverage>`_ to learn more about code coverage with GCOV in ESP-IDF projects.
 
-You can use the **ESP-IDF: Configure Project SDKConfig for Coverage** to set required configuration in the SDK Configuration Editor.
+You can use the ``ESP-IDF: Configure Project SDKConfig for Coverage`` to set the required configuration in the SDK Configuration Editor.
+
 
-Code coverage example
--------------------------------
+Code Coverage Example
+---------------------
 
 Let's use the ESP-IDF `GCOV Example <https://github.com/espressif/esp-idf/tree/master/examples/system/gcov>`_ for this tutorial.
 
-- Navigate to **View** > **Command Palette**.
+1.  Navigate to ``View`` > ``Command Palette``.
 
-- Type **ESP-IDF: New Project** and choose ESP-IDF version to use.
+2.  Type ``ESP-IDF: New Project`` and choose ESP-IDF version to use.
 
-If you don't see the option, please review the current ESP-IDF setup in :ref:`Installation <installation>`.
+    .. note::
 
-- A window will be open with settings to configure the project. Later you can choose from a list a ESP-IDF examples, go the **system** section and choose the ``gcov``. You will see a **Create Project Using Example gcov** button in the top and a description of the project below. Click **Create Project Using Example GCOV** button.
+	    If you don't see the option, please review the current ESP-IDF setup in :ref:`Installation <installation>`.
 
-.. image:: ../../../media/tutorials/coverage/gcov_example.png
+3.  A window will open with settings to configure the project. Choose from a list of ESP-IDF examples, go to the ``system`` section, and select ``gcov``. You will see a ``Create Project Using Example GCOV`` button at the top and a project description below. Click ``Create Project Using Example GCOV``.
 
-- Now select a container directory where to copy the example project. For example, if you choose ``/Users/myUser/someFolder`` the resulting folder will be ``/Users/myUser/someFolder/gcov``. This new project directory will be created and opened in Visual Studio Code.
+    .. image:: ../../../media/tutorials/coverage/gcov_example.png
 
-- First you should select an Espressif target (esp32, esp32s2, etc.) with:
+4.  Select a container directory where to copy the example project. For example, if you choose ``/Users/myUser/someFolder``, the resulting folder will be ``/Users/myUser/someFolder/gcov``. This new project directory will be created and opened in Visual Studio Code.
 
-  - Navigate to **View** > **Command Palette**.
-  - Type **ESP-IDF: Set Espressif Device Target** command. Default is ``esp32`` and the one used in this tutorial.
+5.  Select an Espressif target (esp32, esp32s2, etc.):
 
-- Next configure your sdkconfig project with the **ESP-IDF: Configure Project SDKConfig for Coverage** command or by yourself using the **ESP-IDF: SDK Configuration Editor** command where you can modify the ESP-IDF project settings. After all changes are made, click save and close this window.
+    - Navigate to ``View`` > ``Command Palette``.
+    - Type ``ESP-IDF: Set Espressif Device Target`` command. The default target is ``esp32``, which is used in this tutorial.
 
-.. image:: ../../../media/tutorials/basic_use/gui_menuconfig.png
+6.  Configure your sdkconfig project with the ``ESP-IDF: Configure Project SDKConfig for Coverage`` command or manually using the ``ESP-IDF: SDK Configuration Editor`` command. After all changes are made, click ``Save`` and close the window.
 
-- The example will enable the following options by default:
+    .. image:: ../../../media/tutorials/basic_use/gui_menuconfig.png
 
-  - Enable the Application Tracing Module under ``Component Config`` > ``Application Level Tracing`` > ``Data Destination`` by choosing ``Trace Memory``.
-  - Enable GCOV to host interface under ``Component Config`` > ``Application Level Tracing`` > ``GCOV to Host Enable``.
-  - Enable OpenOCD Debug Stubs under ``Component Config`` > ``ESP32-specific`` > ``OpenOCD Debug Stubs``.
+7.  The example will enable the following options by default:
 
-- Now build the project, flash your device and start the ESP-IDF Monitor you can use the **ESP-IDF: Build your Project**, **ESP-IDF: Flash your Project** and **ESP-IDF: Monitor Device** commands.
+    - Enable the Application Tracing Module under ``Component Config`` > ``Application Level Tracing`` > ``Data Destination`` by choosing ``Trace Memory``.
+    - Enable GCOV to host interface under ``Component Config`` > ``Application Level Tracing`` > ``GCOV to Host Enable``.
+    - Enable OpenOCD Debug Stubs under ``Component Config`` > ``ESP32-specific`` > ``OpenOCD Debug Stubs``.
 
-.. note::
-  There is also a **ESP-IDF: Build, Flash and Start a Monitor on your Device** command which does all three former commands in one.
+8.  Build the project, flash your device, and start the ESP-IDF Monitor using the ``ESP-IDF: Build your Project``, ``ESP-IDF: Flash your Project``, and ``ESP-IDF: Monitor Device`` commands.
 
-- Next step is to launch OpenOCD and send some commands. To start openOCD from the extension, execute the **ESP-IDF: OpenOCD Manager** command or from the ``OpenOCD Server (Running | Stopped)`` button in the Visual Studio Code status bar. OpenOCD server output is shown in menu **View** > **Output** > **ESP-IDF**.
+    .. note::
+  
+        There is also an ``ESP-IDF: Build, Flash and Start a Monitor on your Device`` command that combines all three commands.
 
-- Launch a new terminal with menu **Terminal** > New Terminal and execute ``telnet <oocd_host> <oocd_port>`` which by default is ``telnet localhost 4444``. Latest MacOS users can use ``nc <oocd_host> <oocd_port>`` if ``telnet`` is not in the system.
+9.  Launch OpenOCD and send some commands. To start OpenOCD from the extension, execute the ``ESP-IDF: OpenOCD Manager`` command or use the ``OpenOCD Server (Running | Stopped)`` button in the Visual Studio Code status bar. OpenOCD server output is shown in ``View`` > ``Output`` > ``ESP-IDF``.
 
-.. note::
-  you can modify **openocd.tcl.host** and **openocd.tcl.port** configuration settings to modify these values.
+10. Launch a new terminal with menu ``Terminal`` > ``New Terminal`` and execute ``telnet <oocd_host> <oocd_port>``, which defaults to ``telnet localhost 4444``. Latest macOS users can use ``nc <oocd_host> <oocd_port>`` if ``telnet`` is not available.
 
-- Send the OpenOCD command ``esp gcov dump`` for hard-coded dump which will dump two hard-coded dumps based on this example. After that send the ``esp gcov`` command for instant run-time dump.
+    .. note::
+      
+	    You can modify ``openocd.tcl.host`` and ``openocd.tcl.port`` configuration settings to change these values.
 
-.. image:: ../../../media/tutorials/coverage/oocd_cmds.png
+11. Send the OpenOCD command ``esp gcov dump`` for a hard-coded dump, which will perform two hard-coded dumps based on this example. Then send the ``esp gcov`` command for an instant run-time dump.
 
-- After dumping data one or more times, open the desired file in your editor and execute the **ESP-IDF: Add Editor Coverage** command to highlight the editor with code coverage.
+    .. image:: ../../../media/tutorials/coverage/oocd_cmds.png
 
-- You can customize highlight color using these extension settings.json configuration settings:
+12. After dumping data, open the desired file in your editor and execute the ``ESP-IDF: Add Editor Coverage`` command to highlight the editor with code coverage.
 
-  - Covered lines use **idf.coveredLightTheme** for light themes and **idf.coveredDarkTheme** for dark themes.
-  - Partially covered lines use **idf.partialLightTheme** for light themes and **idf.partialDarkTheme** for dark themes.
-  - Non-covered lines use **idf.uncoveredLightTheme** for light themes and **idf.uncoveredDarkTheme** for dark themes.
+13. You can customize the highlight color through the following configuration settings in the extension’s ``settings.json`` file:
 
-Visual Studio code support ``"red"``, ``rgb(255,0,120)`` or ``rgba(120,0,0,0.1)``.
+    - Covered lines use ``idf.coveredLightTheme`` for light themes and ``idf.coveredDarkTheme`` for dark themes.
+    - Partially covered lines use ``idf.partialLightTheme`` for light themes and ``idf.partialDarkTheme`` for dark themes.
+    - Non-covered lines use ``idf.uncoveredLightTheme`` for light themes and ``idf.uncoveredDarkTheme`` for dark themes.
 
-.. image:: ../../../media/tutorials/coverage/editor_coverage.png
+    Visual Studio Code supports ``red``, ``rgb(255,0,120)`` or ``rgba(120,0,0,0.1)``.
 
-- When finished, use the **ESP-IDF: Remove Editor Coverage** command to remove the code coverage.
+    .. image:: ../../../media/tutorials/coverage/editor_coverage.png
 
-- Navigate to **View** > **Command Palette**.
+14. When finished, use the ``ESP-IDF: Remove Editor Coverage`` command to remove the code coverage.
 
-- Type  **ESP-IDF: Get HTML Coverage Report for Project** select the command to generate a HTML report for code coverage.
+    - Navigate to ``View`` > ``Command Palette``.
+    - Type ``ESP-IDF: Get HTML Coverage Report for Project`` and select the command to generate an HTML report for code coverage.
 
-.. image:: ../../../media/tutorials/coverage/html_report.png
+    .. image:: ../../../media/tutorials/coverage/html_report.png
 
 .. note::
-  * Check the :ref:`Troubleshooting <troubleshooting-section>` section if you have any issues.
+        
+    Check the :ref:`Troubleshooting <troubleshooting-section>` section if you encounter any issues.

docs_espressif/zh_CN/additionalfeatures/coverage.rst

@@ -1 +1,86 @@
-.. include:: ../../en/additionalfeatures/coverage.rst
+代码覆盖率
+==========
+
+:link_to_translation:`en:[English]`
+
+源代码覆盖率提供了程序运行时每条执行路径的执行次数和频率数据。`GCOV <https://en.wikipedia.org/wiki/Gcov>`_ 是一个 GCC 工具，配合编译器使用时，可生成日志文件，显示每一行源代码的执行次数。
+
+使用 ``gcov``，配置 ESP-IDF 项目生成 ``gcda/gcno`` 覆盖率文件。请参阅 `GCOV 代码覆盖率 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/app_trace.html#gcov-source-code-coverage>`_，以详细了解如何在 ESP-IDF 项目中使用 GCOV 的代码覆盖率功能。
+
+可使用 ``ESP-IDF：配置 SDKConfig 文件以启用代码覆盖率`` 命令在 SDK 配置编辑器中设置所需配置。
+
+
+代码覆盖率示例
+--------------
+
+本教程将围绕 ESP-IDF `GCOV 示例 <https://github.com/espressif/esp-idf/tree/master/examples/system/gcov>`_ 展开说明。
+
+1.  前往菜单栏 ``查看`` > ``命令面板``。
+
+2.  输入 ``ESP-IDF：新建项目`` 并选择要使用的 ESP-IDF 版本。
+
+    .. note::
+
+	    如果未看到该选项，请检查当前的 ESP-IDF 设置，详见 :ref:`Installation <installation>`。
+
+3.  系统将弹出用于配置项目的窗口。从 ESP-IDF 示例列表中选择示例，在 ``system`` 部分选择 ``gcov``。页面顶部会出现 ``Create Project Using Example GCOV`` 按钮，页面下方会出现项目描述。点击 ``Create Project Using Example GCOV``。
+
+    .. image:: ../../../media/tutorials/coverage/gcov_example.png
+
+4.  选择容器目录用于复制示例项目。例如，如果选择 ``/Users/myUser/someFolder``，则生成的文件夹将为 ``/Users/myUser/someFolder/gcov``。该新项目目录将被创建并在 Visual Studio Code 中打开。
+
+5.  选择乐鑫目标芯片（如 esp32，esp32s2 等）：
+
+    - 前往菜单栏 ``查看`` > ``命令面板``。
+    - 输入 ``ESP-IDF：设置乐鑫设备目标`` 命令。默认的目标是 ``esp32``，本教程将使用该目标。
+
+6.  使用 ``ESP-IDF：配置 SDKConfig 文件以启用代码覆盖率`` 命令配置 sdkconfig 项目，或使用 ``ESP-IDF：SDK 配置编辑器`` 命令手动配置。完成所有更改后，点击 ``Save`` 并关闭窗口。
+
+    .. image:: ../../../media/tutorials/basic_use/gui_menuconfig.png
+
+7.  该示例默认启用以下选项：
+
+    - 在 ``Component Config`` > ``Application Level Tracing`` > ``Data Destination`` 下选择 ``Trace Memory``，以启用应用跟踪模块。
+    - 在 ``Component Config`` > ``Application Level Tracing`` > ``GCOV to Host Enable`` 下启用 GCOV 到主机接口。
+    - 在 ``Component Config`` > ``ESP32-specific`` > ``OpenOCD Debug Stubs`` 下启用 OpenOCD 调试桩。
+
+8.  通过 ``ESP-IDF：构建项目``、``ESP-IDF：烧录项目`` 和 ``ESP-IDF：监视设备`` 命令构建并烧录项目，启动 ESP-IDF 监视器。
+
+    .. note::
+  
+        也可以直接使用 ``ESP-IDF：构建、烧录项目并监视设备`` 命令一次性执行三个操作。
+
+9.  启动 OpenOCD 并发送命令。要在扩展启动 OpenOCD，请执行 ``ESP-IDF：OpenOCD 管理器`` 命令，或使用 Visual Studio Code 状态栏中的 ``OpenOCD Server（Running | Stopped）`` 按钮。OpenOCD 服务器输出在菜单栏 ``查看`` > ``输出`` > ``ESP-IDF`` 中显示。
+
+10. 前往菜单栏 ``终端`` > ``新建终端``，执行 ``telnet <oocd_host> <oocd_port>``，默认值为 ``telnet localhost 4444``。最新版 macOS 的用户若无法使用 ``telnet``，可使用 ``nc <oocd_host> <oocd_port>``。
+
+    .. note::
+      
+	    可以通过修改 ``openocd.tcl.host`` 和 ``openocd.tcl.port`` 配置项来更改上述值。
+
+11.  发送 OpenOCD 命令 ``esp gcov dump`` 执行硬编码转储，该命令会基于此示例执行两次硬编码转储。然后发送 ``esp gcov`` 命令进行即时运行时转储。
+
+    .. image:: ../../../media/tutorials/coverage/oocd_cmds.png
+
+12. 数据转储完成后，在编辑器中打开所需文件并执行 ``ESP-IDF：添加编辑器覆盖率`` 命令，编辑器将高亮显示代码覆盖率。
+
+13. 可以通过在扩展的 ``settings.json`` 配置文件中添加或修改相应的配置项，自定义高亮颜色。
+
+    - 已覆盖的行在浅色主题中使用 ``idf.coveredLightTheme``，在深色主题中使用 ``idf.coveredDarkTheme``。
+    - 部分覆盖的行在浅色主题中使用 ``idf.partialLightTheme``，在深色主题中使用 ``idf.partialDarkTheme``。
+    - 未覆盖的行在浅色主题中使用 ``idf.uncoveredLightTheme``，在深色主题中使用 ``idf.uncoveredDarkTheme``。
+
+    Visual Studio Code 支持 ``red``、``rgb(255,0,120)`` 或 ``rgba(120,0,0,0.1)`` 格式。
+
+    .. image:: ../../../media/tutorials/coverage/editor_coverage.png
+
+14. 配置完成后，使用 ``ESP-IDF：移除编辑器覆盖率`` 命令移除代码覆盖率。
+
+    - 前往菜单栏 ``查看`` > ``命令面板``。
+    - 输入并选择 ``ESP-IDF：生成 HTML 格式的代码覆盖率报告`` 命令。
+
+    .. image:: ../../../media/tutorials/coverage/html_report.png
+
+.. note::
+        
+    如果遇到任何问题，请查看 :ref:`故障排除 <troubleshooting-section>`。

package.nls.zh-CN.json

@@ -47,7 +47,7 @@
 	"espIdf.flashUart.title": "通过 UART 接口烧录项目",
 	"espIdf.flashPartitionTableUart.title": "闪存分区表 UART",
 	"espIdf.fullClean.title": "彻底清理项目",
-	"espIdf.genCoverage.title": "添加编辑器覆盖率功能",
+	"espIdf.genCoverage.title": "添加编辑器覆盖率",
 	"espIdf.getCoverageReport.title": "生成 HTML 格式的代码覆盖率报告",
 	"espIdf.getEspAdf.title": "安装 ESP-ADF",
 	"espIdf.getEspHomeKitSdk.title": "安装 ESP-HomeKit-SDK",