Merge branch 'docs/sync_up_translation_january' into 'master'

docs: Sync up CN and EN versions for files in api-guides and hw-reference (Jan)

Closes DOC-4458

See merge request espressif/esp-idf!22047

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

@@ -8,13 +8,13 @@ This document explains the implementation of the ESP-IDF build system and the co
 Overview
 ========
 
-An ESP-IDF project can be seen as an amalgamation of a number of components. For example, for a webserver that shows the current humidity, there could be:
+An ESP-IDF project can be seen as an amalgamation of a number of components. For example, for a web server that shows the current humidity, there could be:
 
 - The ESP-IDF base libraries (libc, ROM bindings, etc)
 - The Wi-Fi drivers
 - A TCP/IP stack
 - The FreeRTOS operating system
-- A webserver
+- A web server
 - A driver for the humidity sensor
 - Main code tying it all together
 
@@ -25,17 +25,17 @@ Concepts
 
 - A "project" is a directory that contains all the files and configuration to build a single "app" (executable), as well as additional supporting elements such as a partition table, data/filesystem partitions, and a bootloader.
 
-- "Project configuration" is held in a single file called ``sdkconfig`` in the root directory of the project. This configuration file is modified via ``idf.py menuconfig`` to customise the configuration of the project. A single project contains exactly one project configuration.
+- "Project configuration" is held in a single file called ``sdkconfig`` in the root directory of the project. This configuration file is modified via ``idf.py menuconfig`` to customize the configuration of the project. A single project contains exactly one project configuration.
 
-- An "app" is an executable which is built by ESP-IDF. A single project will usually build two apps - a "project app" (the main executable, ie your custom firmware) and a "bootloader app" (the initial bootloader program which launches the project app).
+- An "app" is an executable that is built by ESP-IDF. A single project will usually build two apps - a "project app" (the main executable, ie your custom firmware) and a "bootloader app" (the initial bootloader program which launches the project app).
 
-- "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.
+- "components" are modular pieces of standalone code that are compiled into static libraries (.a files) and linked to 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 of ESP-IDF can be seen by running `idf.py --list-targets`.
 
 Some things are not part of the project:
 
-- "ESP-IDF" is not part of the project. Instead it is standalone, and linked to the project via the ``IDF_PATH`` environment variable which holds the path of the ``esp-idf`` directory. This allows the IDF framework to be decoupled from your project.
+- "ESP-IDF" is not part of the project. Instead, it is standalone, and linked to the project via the ``IDF_PATH`` environment variable which holds the path of the ``esp-idf`` directory. This allows the IDF framework to be decoupled from your project.
 
 - The toolchain for compilation is not part of the project. The toolchain should be installed in the system command line PATH.
 
@@ -69,11 +69,11 @@ When ``idf.py`` does something, it prints each command that it runs for easy ref
   cmake .. -G Ninja   # or 'Unix Makefiles'
   ninja
 
-In the above list, the ``cmake`` command configures the project and generates build files for use with the final build tool. In this case the final build tool is Ninja_: running ``ninja`` actually builds the project.
+In the above list, the ``cmake`` command configures the project and generates build files for use with the final build tool. In this case, the final build tool is Ninja_: running ``ninja`` actually builds the project.
 
 It's not necessary to run ``cmake`` more than once. After the first build, you only need to run ``ninja`` each time. ``ninja`` will automatically re-invoke ``cmake`` if the project needs reconfiguration.
 
-If using CMake with ``ninja`` or ``make``, there are also targets for more of the ``idf.py`` sub-commands - for example running ``make menuconfig`` or ``ninja menuconfig`` in the build directory will work the same as ``idf.py menuconfig``.
+If using CMake with ``ninja`` or ``make``, there are also targets for more of the ``idf.py`` sub-commands. For example, running ``make menuconfig`` or ``ninja menuconfig`` in the build directory will work the same as ``idf.py menuconfig``.
 
 .. note::
    If you're already familiar with CMake_, you may find the ESP-IDF CMake-based build system unusual because it wraps a lot of CMake's functionality to reduce boilerplate. See `writing pure CMake components`_ for some information about writing more "CMake style" components.
@@ -158,13 +158,13 @@ This example "myProject" contains the following elements:
 
 - A top-level project CMakeLists.txt file. This is the primary file which CMake uses to learn how to build the project; and may set project-wide CMake variables. It includes the file :idf_file:`/tools/cmake/project.cmake` which implements the rest of the build system. Finally, it sets the project name and defines the project.
 
-- "sdkconfig" project configuration file. This file is created/updated when ``idf.py menuconfig`` runs, and holds configuration for all of the components in the project (including ESP-IDF itself). The "sdkconfig" file may or may not be added to the source control system of the project.
+- "sdkconfig" project configuration file. This file is created/updated when ``idf.py menuconfig`` runs, and holds the configuration for all of the components in the project (including ESP-IDF itself). The "sdkconfig" file may or may not be added to the source control system of the project.
 
-- Optional "components" directory contains components that are part of the project. A project does not have to contain custom components of this kind, but it can be useful for structuring reusable code or including third party components that aren't part of ESP-IDF. Alternatively, ``EXTRA_COMPONENT_DIRS`` can be set in the top-level CMakeLists.txt to look for components in other places.
+- Optional "components" directory contains components that are part of the project. A project does not have to contain custom components of this kind, but it can be useful for structuring reusable code or including third-party components that aren't part of ESP-IDF. Alternatively, ``EXTRA_COMPONENT_DIRS`` can be set in the top-level CMakeLists.txt to look for components in other places.
 
 - "main" directory is a special component that contains source code for the project itself. "main" is a default name, the CMake variable ``COMPONENT_DIRS`` includes this component but you can modify this variable. See the :ref:`renaming main <rename-main>` section for more info. If you have a lot of source files in your project, we recommend grouping most into components instead of putting them all in "main".
 
-- "build" directory is where build output is created. This directory is created by ``idf.py`` if it doesn't already exist. CMake configures the project and generates interim build files in this directory. Then, after the main build process is run, this directory will also contain interim object files and libraries as well as final binary output files. This directory is usually not added to source control or distributed with the project source code.
+- "build" directory is where the build output is created. This directory is created by ``idf.py`` if it doesn't already exist. CMake configures the project and generates interim build files in this directory. Then, after the main build process is run, this directory will also contain interim object files and libraries as well as final binary output files. This directory is usually not added to source control or distributed with the project source code.
 
 Component directories each contain a component ``CMakeLists.txt`` file. This file contains variable definitions to control the build process of the component, and its integration into the overall project. See `Component CMakeLists Files`_ for more details.
 
@@ -202,7 +202,7 @@ The inclusion of these three lines, in the order shown above, is necessary for e
 Optional Project Variables
 --------------------------
 
-These variables all have default values that can be overridden for custom behaviour. Look in :idf_file:`/tools/cmake/project.cmake` for all of the implementation details.
+These variables all have default values that can be overridden for custom behavior. Look in :idf_file:`/tools/cmake/project.cmake` for all of the implementation details.
 
 - ``COMPONENT_DIRS``: Directories to search for components. Defaults to ``IDF_PATH/components``, ``PROJECT_DIR/components``, and ``EXTRA_COMPONENT_DIRS``. Override this variable if you don't want to search for components in these places.
 
@@ -219,7 +219,7 @@ To set these variables, use the `cmake set command <cmake set_>`_ ie ``set(VARIA
 Renaming ``main`` Component
 ----------------------------
 
-The build system provides special treatment to the ``main`` component. It is a component that gets automatically added to the build provided that it is in the expected location, PROJECT_DIR/main. All other components in the build are also added as its dependencies, saving the user from hunting down dependencies and providing a build that works right out of the box. Renaming the ``main`` component causes the loss of these behind-the-scenes heavy lifting, requiring the user to specify the location of the newly renamed component and manually specifying its dependencies. Specifically, the steps to renaming ``main`` are as follows:
+The build system provides special treatment to the ``main`` component. It is a component that gets automatically added to the build provided that it is in the expected location, PROJECT_DIR/main. All other components in the build are also added as its dependencies, saving the user from hunting down dependencies and providing a build that works right out of the box. Renaming the ``main`` component causes the loss of these behind-the-scenes heavy lifting, requiring the user to specify the location of the newly renamed component and manually specify its dependencies. Specifically, the steps to renaming ``main`` are as follows:
 
 1. Rename ``main`` directory.
 2. Set ``EXTRA_COMPONENT_DIRS`` in the project CMakeLists.txt to include the renamed ``main`` directory.
@@ -243,7 +243,7 @@ it should be done after ``project()``::
 
     idf_build_set_property(COMPILE_OPTIONS "-Wno-error" APPEND)
 
-This ensures that the compile options set by the user won't be overriden by the default build specifications, since the latter are set inside ``project()``.
+This ensures that the compile options set by the user won't be overridden by the default build specifications, since the latter are set inside ``project()``.
 
 .. _component-directories:
 
@@ -287,7 +287,7 @@ The minimal component ``CMakeLists.txt`` file simply registers the component to
 - ``INCLUDE_DIRS`` is a list of directories to add to the global include search path for any component which requires this component, and also the main source files.
 - ``REQUIRES`` is not actually required, but it is very often required to declare what other components this component will use. See :ref:`component requirements <component-requirements>`.
 
-A library with the name of the component will be built and linked into the final app.
+A library with the name of the component will be built and linked to the final app.
 
 Directories are usually specified relative to the ``CMakeLists.txt`` file itself, although they can be absolute.
 
@@ -310,10 +310,10 @@ The following component-specific variables are available for use inside componen
 The following variables are set at the project level, but available for use in component CMakeLists:
 
 - ``CONFIG_*``: Each value in the project configuration has a corresponding variable available in cmake. All names begin with ``CONFIG_``. :doc:`More information here </api-reference/kconfig>`.
-- ``ESP_PLATFORM``: Set to 1 when the CMake file is processed within ESP-IDF build system.
+- ``ESP_PLATFORM``: Set to 1 when the CMake file is processed within the ESP-IDF build system.
 
 Build/Project Variables
-------------------------
+-----------------------
 
 The following are some project/build variables that are available as build properties and whose values can be queried using ``idf_build_get_property`` from the component CMakeLists.txt:
 
@@ -328,9 +328,9 @@ The following are some project/build variables that are available as build prope
   * If :ref:`CONFIG_APP_PROJECT_VER_FROM_CONFIG` option is set, the value of :ref:`CONFIG_APP_PROJECT_VER` will be used.
   * Else, if ``PROJECT_VER`` variable is set in project CMakeLists.txt file, its value will be used.
   * Else, if the ``PROJECT_DIR/version.txt`` exists, its contents will be used as ``PROJECT_VER``.
-  * Else, if the project is located inside a Git repository, the output of git describe will be used.
+  * Else, if the project is located inside a Git repository, the output of git description will be used.
   * Otherwise, ``PROJECT_VER`` will be "1".
-- ``EXTRA_PARTITION_SUBTYPES``: CMake list of extra partition subtypes. Each subtype description is a comma separated string with ``type_name, subtype_name, numeric_value`` format. Components may add new subtypes by appending them to this list.
+- ``EXTRA_PARTITION_SUBTYPES``: CMake list of extra partition subtypes. Each subtype description is a comma-separated string with ``type_name, subtype_name, numeric_value`` format. Components may add new subtypes by appending them to this list.
 
 Other build properties are listed :ref:`here<cmake-build-properties>`.
 
@@ -395,13 +395,13 @@ When Writing a Component
 
 - ``REQUIRES`` should be set to all components whose header files are #included from the *public* header files of this component.
 
-- ``PRIV_REQUIRES`` should be set to all components whose header files are #included from *any source files* in this component, unless already listed in ``REQUIRES``. Also any component which is required to be linked in order for this component to function correctly.
+- ``PRIV_REQUIRES`` should be set to all components whose header files are #included from *any source files* in this component, unless already listed in ``REQUIRES``. Also, any component which is required to be linked in order for this component to function correctly.
 
-- The values of ``REQUIRES`` and ``PRIV_REQUIRES`` should not depend on any configuration choices (``CONFIG_xxx`` macros). This is because requirements are expanded before configuration is loaded. Other component variables (like include paths or source files) can depend on configuration choices.
+- The values of ``REQUIRES`` and ``PRIV_REQUIRES`` should not depend on any configuration choices (``CONFIG_xxx`` macros). This is because requirements are expanded before the configuration is loaded. Other component variables (like include paths or source files) can depend on configuration choices.
 
 - Not setting either or both ``REQUIRES`` variables is fine. If the component has no requirements except for the `Common component requirements`_ needed for RTOS, libc, etc.
 
-If a components only supports some target chips (values of ``IDF_TARGET``) then it can specify ``REQUIRED_IDF_TARGETS`` in the ``idf_component_register`` call to express these requirements. In this case the build system will generate an error if the component is included into the build, but does not support the selected target.
+If a component only supports some target chips (values of ``IDF_TARGET``) then it can specify ``REQUIRED_IDF_TARGETS`` in the ``idf_component_register`` call to express these requirements. In this case, the build system will generate an error if the component is included in the build, but does not support the selected target.
 
 .. note:: In CMake terms, ``REQUIRES`` & ``PRIV_REQUIRES`` are approximate wrappers around the CMake functions ``target_link_libraries(... PUBLIC ...)`` and ``target_link_libraries(... PRIVATE ...)``.
 
@@ -533,7 +533,7 @@ To avoid duplication, every component automatically requires some "common" IDF c
 The list of common components is: cxx, newlib, freertos, esp_hw_support, heap, log, soc, hal, esp_rom, esp_common, esp_system, xtensa/riscv.
 
 Including Components in the Build
-----------------------------------
+---------------------------------
 
 - By default, every component is included in the build.
 - If you set the ``COMPONENTS`` variable to a minimal list of components used directly by your project, then the build will expand to also include required components. The full list of components will be:
@@ -551,7 +551,7 @@ Circular Dependencies
 
 It's possible for a project to contain Component A that requires (``REQUIRES`` or ``PRIV_REQUIRES``) Component B, and Component B that requires Component A. This is known as a dependency cycle or a circular dependency.
 
-CMake will usually handle circular dependencies automatically by repeating the component library names twice on the linker command line. However this strategy doesn't always work, and it's possible the build will fail with a linker error about "Undefined reference to ...", referencing a symbol defined by one of the components inside the circular dependency. This is particularly likely if there is a large circular dependency, i.e. A->B->C->D->A.
+CMake will usually handle circular dependencies automatically by repeating the component library names twice on the linker command line. However this strategy doesn't always work, and the build may fail with a linker error about "Undefined reference to ...", referencing a symbol defined by one of the components inside the circular dependency. This is particularly likely if there is a large circular dependency, i.e. A->B->C->D->A.
 
 The best solution is to restructure the components to remove the circular dependency. In most cases, a software architecture without circular dependencies has desirable properties of modularity and clean layering and will be more maintainable in the long term. However, removing circular dependencies is not always possible.
 
@@ -571,7 +571,7 @@ For example:
 Advanced Workaround: Undefined Symbols
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If only one or two symbols is causing a circular dependency, and all other dependencies are linear, then there is an alternative method to avoid linker errors: Specify the specific symbols required for the "reverse" dependency as undefined symbols at link time.
+If only one or two symbols are causing a circular dependency, and all other dependencies are linear, then there is an alternative method to avoid linker errors: Specify the specific symbols required for the "reverse" dependency as undefined symbols at link time.
 
 For example, if component A depends on component B but component B also needs to reference ``reverse_ops`` from component A (but nothing else), then you can add a line like the following to the component B CMakeLists.txt to resolve the cycle at link time:
 
@@ -592,7 +592,7 @@ Requirements in the Build System Implementation
 -----------------------------------------------
 
 - Very early in the CMake configuration process, the script ``expand_requirements.cmake`` is run. This script does a partial evaluation of all component CMakeLists.txt files and builds a graph of component requirements (this :ref:`graph may have cycles <component-circular-dependencies>`). The graph is used to generate a file ``component_depends.cmake`` in the build directory.
-- The main CMake process then includes this file and uses it to determine the list of components to include in the build (internal ``BUILD_COMPONENTS`` variable). The ``BUILD_COMPONENTS`` variable is sorted so dependencies are listed first, however as the component dependency graph has cycles this cannot be guaranteed for all components. The order should be deterministic given the same set of components and component dependencies.
+- The main CMake process then includes this file and uses it to determine the list of components to include in the build (internal ``BUILD_COMPONENTS`` variable). The ``BUILD_COMPONENTS`` variable is sorted so dependencies are listed first, however, as the component dependency graph has cycles this cannot be guaranteed for all components. The order should be deterministic given the same set of components and component dependencies.
 - The value of ``BUILD_COMPONENTS`` is logged by CMake as "Component names: "
 - Configuration is then evaluated for the components included in the build.
 - Each component is included in the build normally and the CMakeLists.txt file is evaluated again to add the component libraries to the build.
@@ -602,7 +602,7 @@ Component Dependency Order
 
 The order of components in the ``BUILD_COMPONENTS`` variable determines other orderings during the build:
 
-- Order that :ref:`project_include.cmake` files are included into the project.
+- Order that :ref:`project_include.cmake` files are included in the project.
 - Order that the list of header paths is generated for compilation (via ``-I`` argument). (Note that for a given component's source files, only that component's dependency's header paths are passed to the compiler.)
 
 Adding Link-Time Dependencies
@@ -632,22 +632,22 @@ Overriding Parts of the Project
 project_include.cmake
 ---------------------
 
-For components that have build requirements which must be evaluated before any component CMakeLists files are evaluated, you can create a file called ``project_include.cmake`` in the component directory. This CMake file is included when ``project.cmake`` is evaluating the entire project.
+For components that have build requirements that must be evaluated before any component CMakeLists files are evaluated, you can create a file called ``project_include.cmake`` in the component directory. This CMake file is included when ``project.cmake`` is evaluating the entire project.
 
 ``project_include.cmake`` files are used inside ESP-IDF, for defining project-wide build features such as ``esptool.py`` command line arguments and the ``bootloader`` "special app".
 
 Unlike component ``CMakeLists.txt`` files, when including a ``project_include.cmake`` file the current source directory (``CMAKE_CURRENT_SOURCE_DIR`` and working directory) is the project directory. Use the variable ``COMPONENT_DIR`` for the absolute directory of the component.
 
-Note that ``project_include.cmake`` isn't necessary for the most common component uses - such as adding include directories to the project, or ``LDFLAGS`` to the final linking step. These values can be customised via the ``CMakeLists.txt`` file itself. See `Optional Project Variables`_ for details.
+Note that ``project_include.cmake`` isn't necessary for the most common component uses, such as adding include directories to the project, or ``LDFLAGS`` to the final linking step. These values can be customized via the ``CMakeLists.txt`` file itself. See `Optional Project Variables`_ for details.
 
 ``project_include.cmake`` files are included in the order given in ``BUILD_COMPONENTS`` variable (as logged by CMake). This means that a component's ``project_include.cmake`` file will be included after it's all dependencies' ``project_include.cmake`` files, unless both components are part of a dependency cycle. This is important if a ``project_include.cmake`` file relies on variables set by another component. See also :ref:`above<component-requirements-implementation>`.
 
-Take great care when setting variables or targets in a ``project_include.cmake`` file. As the values are included into the top-level project CMake pass, they can influence or break functionality across all components!
+Take great care when setting variables or targets in a ``project_include.cmake`` file. As the values are included in the top-level project CMake pass, they can influence or break functionality across all components!
 
 KConfig.projbuild
 -----------------
 
-This is an equivalent to ``project_include.cmake`` for :ref:`component-configuration` KConfig files. If you want to include configuration options at the top-level of menuconfig, rather than inside the "Component Configuration" sub-menu, then these can be defined in the KConfig.projbuild file alongside the ``CMakeLists.txt`` file.
+This is an equivalent to ``project_include.cmake`` for :ref:`component-configuration` KConfig files. If you want to include configuration options at the top level of menuconfig, rather than inside the "Component Configuration" sub-menu, then these can be defined in the KConfig.projbuild file alongside the ``CMakeLists.txt`` file.
 
 Take care when adding configuration values in this file, as they will be included across the entire project configuration. Where possible, it's generally better to create a KConfig file for :ref:`component-configuration`.
 
@@ -673,7 +673,7 @@ This mechanism is shown in the example :example:`build_system/wrappers`. Check :
 Configuration-Only Components
 =============================
 
-Special components which contain no source files, only ``Kconfig.projbuild`` and ``KConfig``, can have a one-line ``CMakeLists.txt`` file which calls the function ``idf_component_register()`` with no arguments specified. This function will include the component in the project build, but no library will be built *and* no header files will be added to any include paths.
+Special components which contain no source files, only ``Kconfig.projbuild`` and ``KConfig``, can have a one-line ``CMakeLists.txt`` file which calls the function ``idf_component_register()`` with no arguments specified. This function will include the component in the project build, but no library will be built *and* no header files will be added to any included paths.
 
 Debugging CMake
 ===============
@@ -746,13 +746,13 @@ This can also be used to select or stub out an implementation, as such:
     config ENABLE_LCD_OUTPUT
         bool "Enable LCD output."
         help
-            Select this if your board has a LCD.
+            Select this if your board has an LCD.
 
     config ENABLE_LCD_CONSOLE
         bool "Output console text to LCD"
         depends on ENABLE_LCD_OUTPUT
         help
-            Select this to output debugging output to the lcd
+            Select this to output debugging output to the LCD
 
     config ENABLE_LCD_PLOT
         bool "Output temperature plots to LCD"
@@ -806,7 +806,7 @@ Some components will have a situation where a source file isn't supplied with th
 
 This answer is adapted from the `CMake FAQ entry <cmake faq generated files_>`_, which contains some other examples that will also work with ESP-IDF builds.
 
-In this example, logo.h will be generated in the current directory (the build directory) while logo.bmp comes with the component and resides under the component path. Because logo.h is a generated file, it should be cleaned when the project is cleaned. For this reason it is added to the `ADDITIONAL_MAKE_CLEAN_FILES`_ property.
+In this example, logo.h will be generated in the current directory (the build directory) while logo.bmp comes with the component and resides under the component path. Because logo.h is a generated file, it should be cleaned when the project is cleaned. For this reason, it is added to the `ADDITIONAL_MAKE_CLEAN_FILES`_ property.
 
 .. note::
 
@@ -819,7 +819,7 @@ If a a source file from another component included ``logo.h``, then ``add_depend
 Embedding Binary Data
 ---------------------
 
-Sometimes you have a file with some binary or text data that you'd like to make available to your component - but you don't want to reformat the file as C source.
+Sometimes you have a file with some binary or text data that you'd like to make available to your component, but you don't want to reformat the file as a C source.
 
 You can specify argument ``EMBED_FILES`` in the component registration, giving space-delimited names of the files to embed::
 
@@ -852,7 +852,7 @@ For an example of using this technique, see the "main" component of the file_ser
 
 .. highlight:: cmake
 
-It is also possible embed a generated file::
+It is also possible to embed a generated file::
 
   add_custom_command(OUTPUT my_processed_file.bin
                     COMMAND my_process_file_cmd my_unprocessed_file.bin)
@@ -909,7 +909,7 @@ Obviously, there are cases where all these recipes are insufficient for a certai
 - ``externalproject_add`` defines an external build system.
 
   - ``SOURCE_DIR``, ``CONFIGURE_COMMAND``, ``BUILD_COMMAND`` and ``INSTALL_COMMAND`` should always be set. ``CONFIGURE_COMMAND`` can be set to an empty string if the build system has no "configure" step. ``INSTALL_COMMAND`` will generally be empty for ESP-IDF builds.
-  - Setting ``BUILD_IN_SOURCE`` means the build directory is the same as the source directory. Otherwise you can set ``BUILD_DIR``.
+  - Setting ``BUILD_IN_SOURCE`` means the build directory is the same as the source directory. Otherwise, you can set ``BUILD_DIR``.
   - Consult the ExternalProject_ documentation for more details about ``externalproject_add()``
 
 - The second set of commands adds a library target, which points to the "imported" library file built by the external system. Some properties need to be set in order to add include directories and tell CMake where this file is.
@@ -924,14 +924,14 @@ Obviously, there are cases where all these recipes are insufficient for a certai
 ExternalProject Dependencies and Clean Builds
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-CMake has some unusual behaviour around external project builds:
+CMake has some unusual behavior around external project builds:
 
 - `ADDITIONAL_MAKE_CLEAN_FILES`_ only works when "make" is used as the build system. If Ninja_ or an IDE build system is used, it won't delete these files when cleaning.
 - However, the ExternalProject_ configure & build commands will *always* be re-run after a clean is run.
 - Therefore, there are two alternative recommended ways to configure the external build command:
 
     1. Have the external ``BUILD_COMMAND`` run a full clean compile of all sources. The build command will be run if any of the dependencies passed to ``externalproject_add`` with ``DEPENDS`` have changed, or if this is a clean build (ie any of ``idf.py clean``, ``ninja clean``, or ``make clean`` was run.)
-    2. Have the external ``BUILD_COMMAND`` be an incremental build command. Pass the parameter ``BUILD_ALWAYS 1`` to ``externalproject_add``. This means the external project will be built each time a build is run, regardless of dependencies. This is only recommended if the external project has correct incremental build behaviour, and doesn't take too long to run.
+    2. Have the external ``BUILD_COMMAND`` be an incremental build command. Pass the parameter ``BUILD_ALWAYS 1`` to ``externalproject_add``. This means the external project will be built each time a build is run, regardless of dependencies. This is only recommended if the external project has correct incremental build behavior, and doesn't take too long to run.
 
 The best of these approaches for building an external project will depend on the project itself, its build system, and whether you anticipate needing to frequently recompile the project.
 
@@ -942,9 +942,9 @@ Custom Sdkconfig Defaults
 
 For example projects or other projects where you don't want to specify a full sdkconfig configuration, but you do want to override some key values from the ESP-IDF defaults, it is possible to create a file ``sdkconfig.defaults`` in the project directory. This file will be used when creating a new config from scratch, or when any new config value hasn't yet been set in the ``sdkconfig`` file.
 
-To override the name of this file or to specify multiple files, set the ``SDKCONFIG_DEFAULTS`` environment variable or set ``SDKCONFIG_DEFAULTS`` in top-level ``CMakeLists.txt``. File names that are not specified as full paths are resolved relative to current project's diretory.
+To override the name of this file or to specify multiple files, set the ``SDKCONFIG_DEFAULTS`` environment variable or set ``SDKCONFIG_DEFAULTS`` in top-level ``CMakeLists.txt``. File names that are not specified as full paths are resolved relative to current project's directory.
 
-When specifying multiple files, use a semicolon as the list separator. Files listed first will be applied first. If a particular key is defined in multiple files, the definition in the latter file will overide definitions from former files.
+When specifying multiple files, use a semicolon as the list separator. Files listed first will be applied first. If a particular key is defined in multiple files, the definition in the latter file will override definitions from former files.
 
 Some of the IDF examples include a ``sdkconfig.ci`` file. This is part of the continuous integration (CI) test framework and is ignored by the normal build process.
 
@@ -983,7 +983,7 @@ The build directory also contains a generated file ``flasher_args.json`` which c
 Building the Bootloader
 =======================
 
-The bootloader is a special "subproject" inside :idf:`/components/bootloader/subproject`. It has its own project CMakeLists.txt file and builds separate .ELF and .BIN files to the main project. However it shares its configuration and build directory with the main project.
+The bootloader is a special "subproject" inside :idf:`/components/bootloader/subproject`. It has its own project CMakeLists.txt file and builds separate .ELF and .BIN files to the main project. However, it shares its configuration and build directory with the main project.
 
 The subproject is inserted as an external project from the top-level project, by the file :idf_file:`/components/bootloader/project_include.cmake`. The main build process runs CMake for the subproject, which includes discovering components (a subset of the main components) and generating a bootloader-specific config (derived from the main ``sdkconfig``).
 
@@ -1007,7 +1007,7 @@ Here is an example minimal "pure CMake" component CMakeLists file for a componen
   target_include_directories(json PUBLIC cJSON)
 
 - This is actually an equivalent declaration to the IDF ``json`` component :idf_file:`/components/json/CMakeLists.txt`.
-- This file is quite simple as there are not a lot of source files. For components with a large number of files, the globbing behaviour of ESP-IDF's component logic can make the component CMakeLists style simpler.)
+- This file is quite simple as there are not a lot of source files. For components with a large number of files, the globbing behavior of ESP-IDF's component logic can make the component CMakeLists style simpler.)
 - Any time a component adds a library target with the component name, the ESP-IDF build system will automatically add this to the build, expose public include directories, etc. If a component wants to add a library target with a different name, dependencies will need to be added manually via CMake commands.
 
 Using Third-Party CMake Projects with Components
@@ -1078,7 +1078,7 @@ For an example, take a look at :example:`build_system/cmake/import_prebuilt`.
 Using ESP-IDF in Custom CMake Projects
 ======================================
 
-ESP-IDF provides a template CMake project for easily creating an application. However, in some instances the user might already have an existing CMake project or may want to create a custom one. In these cases it is desirable to be able to consume IDF components as libraries to be linked to the user's targets (libraries/ executables).
+ESP-IDF provides a template CMake project for easily creating an application. However, in some instances the user might already have an existing CMake project or may want to create a custom one. In these cases it is desirable to be able to consume IDF components as libraries to be linked to the user's targets (libraries/executables).
 
 It is possible to do so by using the :ref:`build system APIs provided<cmake_buildsystem_api>` by :idf_file:`tools/cmake/idf.cmake`. For example:
 
@@ -1302,7 +1302,7 @@ These are properties that describe a component. Values of component properties c
 - MANAGED_PRIV_REQUIRES - list of private component dependencies added by the IDF component manager from dependencies in ``idf_component.yml`` manifest file
 - MANAGED_REQUIRES - list of public component dependencies added by the IDF component manager from dependencies in ``idf_component.yml`` manifest file
 - PRIV_INCLUDE_DIRS - list of component private include directories; set from ``idf_component_register`` PRIV_INCLUDE_DIRS on components of type LIBRARY
-- PRIV_REQUIRES - list of private component dependentices; set from value of ``idf_component_register`` PRIV_REQUIRES argument and dependencies in ``idf_component.yml`` manifest file
+- PRIV_REQUIRES - list of private component dependencies; set from value of ``idf_component_register`` PRIV_REQUIRES argument and dependencies in ``idf_component.yml`` manifest file
 - REQUIRED_IDF_TARGETS - list of targets the component supports; set from ``idf_component_register`` EMBED_TXTFILES argument
 - REQUIRES - list of public component dependencies; set from value of ``idf_component_register`` REQUIRES argument and dependencies in ``idf_component.yml`` manifest file
 - SRCS - list of component source files; set from SRCS or SRC_DIRS/EXCLUDE_SRCS argument of ``idf_component_register``
@@ -1357,8 +1357,6 @@ For integration into IDEs and other build systems, when CMake runs the build pro
 JSON Configuration Server
 -------------------------
 
-.. highlight :: json
-
 A tool called ``kconfserver`` is provided to allow IDEs to easily integrate with the configuration system logic. ``kconfserver`` is designed to run in the background and interact with a calling process by reading and writing JSON over process stdin & stdout.
 
 You can run ``kconfserver`` from a project via ``idf.py confserver`` or ``ninja kconfserver``, or a similar target triggered from a different build generator.
@@ -1366,7 +1364,7 @@ You can run ``kconfserver`` from a project via ``idf.py confserver`` or ``ninja
 For more information about ``kconfserver``, see the `esp-idf-kconfig documentation <https://github.com/espressif/esp-idf-kconfig/blob/master/docs/DOCUMENTATION.md>`_.
 
 Build System Internals
-=======================
+======================
 
 Build Scripts
 -------------

docs/en/api-guides/dfu.rst

@@ -1,5 +1,5 @@
 Device Firmware Upgrade via USB
-========================================
+===============================
 
 :link_to_translation:`zh_CN:[中文]`
 
@@ -65,7 +65,7 @@ The command below will create a DFU image named ``dfu.bin`` that is placed in th
 .. _api_guide_dfu_flash:
 
 Flashing the DFU Image
-====================================
+======================
 
 The command below will download the DFU image into the {IDF_TARGET_NAME}::
 
@@ -90,7 +90,7 @@ See :ref:`api_guide_dfu_flash_errors` and their solutions.
 
 .. _api_guide_dfu_flash_udev:
 
-Udev Rule (Linux only)
+Udev Rule (Linux Only)
 ----------------------
 
 Udev is a device manager for the Linux kernel. It allows us to run ``dfu-util`` (and ``idf.py dfu-flash``) without ``sudo`` for gaining access to the chip.
@@ -106,7 +106,7 @@ Restart your computer so the previous setting could take into affect or run ``su
 
 .. _api_guide_dfu_flash_win:
 
-USB Drivers (Windows only)
+USB Drivers (Windows Only)
 --------------------------
 
 ``dfu-util`` uses `libusb` to access the device. You have to register on Windows the device with the `WinUSB` driver.
@@ -129,7 +129,6 @@ Common Errors and Known Issues
 
 - Flashing with ``dfu-util`` on Windows fails on the first attempt with error ``Lost device after RESET?``. Please retry the flashing and it should succeed the next time.
 
-
 .. only:: SOC_SUPPORTS_SECURE_DL_MODE
 
     Secure Download Mode

docs/en/api-guides/fatal-errors.rst

@@ -395,8 +395,8 @@ This CPU exception indicates that the instruction which was executed was not a v
 
     Application has attempted to read or write memory location, and address alignment did not match load/store size. For example, 32-bit load can only be done from 4-byte aligned address, and 16-bit load can only be done from a 2-byte aligned address.
 
-Interrupt wdt timeout on CPU0 / CPU1
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Interrupt Watchdog Timeout on CPU0/CPU1
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Indicates that an interrupt watchdog timeout has occurred. See :doc:`Watchdogs <../api-reference/system/wdts>` for more information.
 
@@ -472,7 +472,7 @@ The backtrace should point to the function where stack smashing has occurred. Ch
     .. |ILLEGAL_INSTR_MSG| replace:: Illegal instruction
     .. |CACHE_ERR_MSG| replace:: Cache error
 
-Undefined behavior sanitizer (UBSAN) checks
+Undefined Behavior Sanitizer (UBSAN) Checks
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Undefined behavior sanitizer (UBSAN) is a compiler feature which adds run-time checks for potentially incorrect operations, such as:
@@ -509,7 +509,7 @@ To enable UBSAN for a specific component (``component_name``) from ``CMakeLists.
 
     target_compile_options(${COMPONENT_LIB} PRIVATE "-fsanitize=undefined" "-fno-sanitize=shift-base")
 
-UBSAN output
+UBSAN Output
 """"""""""""
 
 When UBSAN detects an error, a message and the backtrace are printed, for example::

docs/en/api-guides/unit-tests.rst

@@ -9,7 +9,7 @@ ESP-IDF provides the following methods to test software.
 - Linux-host based unit tests in which part of the hardware can be abstracted via mocks. Currently, Linux-host based tests are still under development and only a small fraction of IDF components support them. More information on running IDF applications on the host can be found here: :doc:`Running Applications on the Host Machine <host-apps>`.
 
 Normal Test Cases
-------------------
+-----------------
 
 Unit tests are located in the ``test`` subdirectory of a component. Tests are written in C, and a single C source file can contain multiple test cases. Test files start with the word "test".
 
@@ -44,7 +44,7 @@ See http://www.throwtheswitch.org/unity for more information about writing tests
 
 
 Multi-device Test Cases
--------------------------
+-----------------------
 
 The normal test cases will be executed on one DUT (Device Under Test). However, components that require some form of communication (e.g., GPIO, SPI) require another device to communicate with, thus cannot be tested through normal test cases. Multi-device test cases involve writing multiple test functions, and running them on multiple DUTs.
 
@@ -97,7 +97,7 @@ Once the signal is sent from DUT2, you need to press "Enter" on DUT1, then DUT1
 
 
 Multi-stage Test Cases
------------------------
+----------------------
 
 The normal test cases are expected to finish without reset (or only need to check if reset happens). Sometimes we expect to run some specific tests after certain kinds of reset. For example, we want to test if the reset reason is correct after a wake up from deep sleep. We need to create a deep-sleep reset first and then check the reset reason. To support this, we can define multi-stage test cases, to group a set of test functions::
 
@@ -118,7 +118,7 @@ The normal test cases are expected to finish without reset (or only need to chec
 Multi-stage test cases present a group of test functions to users. It needs user interactions (select cases and select different stages) to run the case.
 
 Tests For Different Targets
-------------------------------
+---------------------------
 
 Some tests (especially those related to hardware) cannot run on all targets. Below is a guide how to make your unit tests run on only specified targets.
 
@@ -219,11 +219,8 @@ The normal case will print the case name and description. Master-slave cases wil
 Test cases can be run by inputting one of the following:
 
 - Test case name in quotation marks to run a single test case
-
 - Test case index to run a single test case
-
 - Module name in square brackets to run all test cases for a specific module
-
 - An asterisk to run all test cases
 
 ``[multi_device]`` and ``[multi_stage]`` tags tell the test runner whether a test case is a multiple devices or multiple stages of test case. These tags are automatically added by ```TEST_CASE_MULTIPLE_STAGES`` and ``TEST_CASE_MULTIPLE_DEVICES`` macros.
@@ -250,7 +247,7 @@ First time you execute this case, input ``1`` to run first stage (trigger deepsl
 .. _cache-compensated-timer:
 
 Timing Code with Cache Compensated Timer
------------------------------------------
+----------------------------------------
 
 Instructions and data stored in external memory (e.g. SPI Flash and SPI RAM) are accessed through the CPU's unified instruction and data cache. When code or data is in cache, access is very fast (i.e., a cache hit).
 
@@ -313,7 +310,7 @@ Mock a Component
 
 If a mocked component, called a *component mock*, is already available in ESP-IDF, then it can be used right away as long as it satisfies the required functionality. Refer to :ref:`component-linux-mock-support` to see which components are mocked already. Then refer to :ref:`adjustments_for_mocks` in order to use the component mock.
 
-If IDF does not yet provide any component mock, it has to be created. To create a component mock, the component needs to be overwritten in a particular way. Overriding a component entails creating a component with the exact same name as the original component, then let the build system discover it later than the original component (see :ref:`Multiple components with the same name <cmake-components-same-name>` for more details).
+It is necessary to create component mocks if they are not yet provided in ESP-IDF. To create a component mock, the component needs to be overwritten in a particular way. Overriding a component entails creating a component with the exact same name as the original component, then letting the build system discover it later than the original component (see :ref:`Multiple components with the same name <cmake-components-same-name>` for more details).
 
 In the component mock, the following parts are specified:
 
@@ -345,7 +342,7 @@ For more details about the CMock configuration yaml file, have a look at :compon
 
 Note that the component mock does not have to mock the original component in its entirety. As long as the test project's dependencies and dependencies of other code to the original components are satisfied by the component mock, partial mocking is adequate. In fact, most of the component mocks in IDF in ``tools/mocks`` are only partially mocking the original component.
 
-Examples of component mocks can be found under :idf:`tools/mocks` in the IDF directory. General information on how to *override an IDF component* can be found in :ref:`Multiple components with the same name <cmake-components-same-name>`. There are several examples for testing code while mocking dependencies with CMock (non-exhaustive list): 
+Examples of component mocks can be found under :idf:`tools/mocks` in the IDF directory. General information on how to *override an IDF component* can be found in :ref:`Multiple components with the same name <cmake-components-same-name>`. There are several examples for testing code while mocking dependencies with CMock (non-exhaustive list):
 
 - :component_file:`unit test for the NVS Page class <nvs_flash/host_test/nvs_page_test/README.md>`.
 - :component_file:`unit test for esp_event <esp_event/host_test/esp_event_unit_test/main/esp_event_test.cpp>`.

docs/en/hw-reference/esp32/get-started-wrover-kit.rst

@@ -2,7 +2,7 @@ ESP-WROVER-KIT V4.1 Getting Started Guide
 =========================================
 :link_to_translation:`zh_CN:[中文]`
 
-This guide shows how to get started with the ESP-WROVER-KIT V4.1 development board and also provides information about its functionality and configuration options. 
+This guide shows how to get started with the ESP-WROVER-KIT V4.1 development board and also provides information about its functionality and configuration options.
 
 
 What You Need
@@ -26,7 +26,7 @@ ESP-WROVER-KIT features the following integrated components:
 - LCD screen
 - microSD card slot
 
-Its another distinguishing feature is the embedded FTDI FT2232HL chip - an advanced multi-interface USB bridge. This chip enables to use JTAG for direct debugging of ESP32 through the USB interface without a separate JTAG debugger. ESP-WROVER-KIT makes development convenient, easy, and cost-effective.
+Another distinguishing feature is the embedded FTDI FT2232HL chip, an advanced multi-interface USB bridge. This chip enables to use JTAG for direct debugging of ESP32 through the USB interface without a separate JTAG debugger. ESP-WROVER-KIT makes development convenient, easy, and cost-effective.
 
 Most of the ESP32 I/O pins are broken out to the board's pin headers for easy access.
 
@@ -125,7 +125,7 @@ The table below provides description in the following manner:
       - All the pins on the ESP32 module are broken out to pin headers. You can program ESP32 to enable multiple functions, such as PWM, ADC, DAC, I2C, I2S, SPI, etc.
     * - microSD Card Slot
       - Useful for developing applications that access microSD card for data storage and retrieval.
-    * - LCD 
+    * - LCD
       - Support for mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown in figure :ref:`get-started-esp-wrover-kit-v4.1-board-back`.
 
 
@@ -148,7 +148,7 @@ There are three jumper blocks available to set up the board functionality. The m
       - |jp7-ext_5v|
       - Power ESP-WROVER-KIT via an external power supply
     * - JP7
-      - |jp7-usb_5v|      
+      - |jp7-usb_5v|
       - Power ESP-WROVER-KIT via USB
     * - JP2
       - |jp2-jtag|
@@ -241,17 +241,17 @@ The JP1 connector consists of 14x2 male pins whose functions are shown in the mi
     * - JTAG, microSD
       - IO15
       - 5V
-      - 
+      -
 
 Legend:
 
 * NC/XTAL - :ref:`32.768 kHz Oscillator <get-started-esp-wrover-kit-v4.1-xtal>`
-* JTAG - :ref:`JTAG / JP2 <get-started-esp-wrover-kit-v4.1-jtag-header>`
-* Boot - Boot button / SW2
-* Camera - :ref:`Camera / JP4 <get-started-esp-wrover-kit-v4.1-camera-header>`
+* JTAG - :ref:`JTAG/JP2 <get-started-esp-wrover-kit-v4.1-jtag-header>`
+* Boot - Boot button/SW2
+* Camera - :ref:`Camera/JP4 <get-started-esp-wrover-kit-v4.1-camera-header>`
 * LED - :ref:`RGB LED <get-started-esp-wrover-kit-v4.1-rgb-led-connections>`
-* microSD - :ref:`microSD Card / J4 <get-started-esp-wrover-kit-v4.1-microsd-card-slot>`
-* LCD - :ref:`LCD / U5 <get-started-esp-wrover-kit-v4.1-lcd-connector>`
+* microSD - :ref:`microSD Card/J4 <get-started-esp-wrover-kit-v4.1-microsd-card-slot>`
+* LCD - :ref:`LCD/U5 <get-started-esp-wrover-kit-v4.1-lcd-connector>`
 * PSRAM - ESP32-WROVER-E's PSRAM
 
 
@@ -274,23 +274,23 @@ Legend:
 
 .. _get-started-esp-wrover-kit-v4.1-spi-flash-header:
 
-SPI Flash / JP2
+SPI Flash/JP2
 ^^^^^^^^^^^^^^^
 
 ====  =============
 .     ESP32 Pin
 ====  =============
-1     CLK / GPIO6
-2     SD0 / GPIO7
-3     SD1 / GPIO8
-4     SD2 / GPIO9
-5     SD3 / GPIO10
-6     CMD / GPIO11
+1     CLK/GPIO6
+2     SD0/GPIO7
+3     SD1/GPIO8
+4     SD2/GPIO9
+5     SD3/GPIO10
+6     CMD/GPIO11
 ====  =============
 
 .. note::
 
-    SPI Flash pins are used to access the internal flash memory, therefore they are not available to connect external SPI devices. Those pins are exposed for monitoring or for advanced usage only.
+    SPI Flash pins are used to access the internal flash memory. Therefore, they are not available to connect external SPI devices. Those pins are exposed for monitoring or for advanced usage only.
 
 .. important::
 
@@ -299,23 +299,23 @@ SPI Flash / JP2
 
 .. _get-started-esp-wrover-kit-v4.1-jtag-header:
 
-JTAG / JP2
+JTAG/JP2
 ^^^^^^^^^^
 
 ====  ==============  =============
 .     ESP32 Pin       JTAG Signal
 ====  ==============  =============
 1     EN              TRST_N
-2     MTMS / GPIO14   TMS
-3     MTDO / GPIO15   TDO
-4     MTDI / GPIO12   TDI
-5     MTCK / GPIO13   TCK
+2     MTMS/GPIO14     TMS
+3     MTDO/GPIO15     TDO
+4     MTDI/GPIO12     TDI
+5     MTCK/GPIO13     TCK
 ====  ==============  =============
 
 
 .. _get-started-esp-wrover-kit-v4.1-camera-header:
 
-Camera / JP4
+Camera/JP4
 ^^^^^^^^^^^^
 
 ====  ==========  =============================
@@ -323,22 +323,22 @@ Camera / JP4
 ====  ==========  =============================
  1    n/a         3.3V
  2    n/a         Ground
- 3    GPIO27      SIO_C / SCCB Clock
- 4    GPIO26      SIO_D / SCCB Data
- 5    GPIO25      VSYNC / Vertical Sync
- 6    GPIO23      HREF / Horizontal Reference
- 7    GPIO22      PCLK / Pixel Clock
- 8    GPIO21      XCLK / System Clock
- 9    GPIO35      D7 / Pixel Data Bit 7
-10    GPIO34      D6 / Pixel Data Bit 6
-11    GPIO39      D5 / Pixel Data Bit 5
-12    GPIO36      D4 / Pixel Data Bit 4
-13    GPIO19      D3 / Pixel Data Bit 3
-14    GPIO18      D2 / Pixel Data Bit 2
-15    GPIO5       D1 / Pixel Data Bit 1
-16    GPIO4       D0 / Pixel Data Bit 0
-17    GPIO0       RESET / Camera Reset
-18    n/a         PWDN / Camera Power Down
+ 3    GPIO27      SIO_C/SCCB Clock
+ 4    GPIO26      SIO_D/SCCB Data
+ 5    GPIO25      VSYNC/Vertical Sync
+ 6    GPIO23      HREF/Horizontal Reference
+ 7    GPIO22      PCLK/Pixel Clock
+ 8    GPIO21      XCLK/System Clock
+ 9    GPIO35      D7/Pixel Data Bit 7
+10    GPIO34      D6/Pixel Data Bit 6
+11    GPIO39      D5/Pixel Data Bit 5
+12    GPIO36      D4/Pixel Data Bit 4
+13    GPIO19      D3/Pixel Data Bit 3
+14    GPIO18      D2/Pixel Data Bit 2
+15    GPIO5       D1/Pixel Data Bit 1
+16    GPIO4       D0/Pixel Data Bit 0
+17    GPIO0       RESET/Camera Reset
+18    n/a         PWDN/Camera Power Down
 ====  ==========  =============================
 
 * Signals D0 .. D7 denote camera data bus
@@ -366,10 +366,10 @@ microSD Card
 ====  ==============  ===============
 .     ESP32 Pin       microSD Signal
 ====  ==============  ===============
-1     MTDI / GPIO12   DATA2
-2     MTCK / GPIO13   CD / DATA3
-3     MTDO / GPIO15   CMD
-4     MTMS / GPIO14   CLK
+1     MTDI/GPIO12     DATA2
+2     MTCK/GPIO13     CD/DATA3
+3     MTDO/GPIO15     CMD
+4     MTMS/GPIO14     CLK
 5     GPIO2           DATA0
 6     GPIO4           DATA1
 7     GPIO21          Card Detect
@@ -378,7 +378,7 @@ microSD Card
 
 .. _get-started-esp-wrover-kit-v4.1-lcd-connector:
 
-LCD / U5
+LCD/U5
 ^^^^^^^^
 
 ====  ==============  ===============
@@ -419,7 +419,7 @@ Power up from USB port    Enable UART communication
 
 Do not install any other jumpers.
 
-Turn the **Power Switch** to ON, and the **5V Power On LED** should light up.
+Turn the **Power Switch** to ON, and the **5 V Power On LED** should light up.
 
 Now to Development
 ^^^^^^^^^^^^^^^^^^
@@ -440,7 +440,7 @@ Related Documents
 
 * `ESP-WROVER-KIT V4.1 schematic`_ (PDF)
 * `ESP-WROVER-KIT V4.1 layout <https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_V4.1.dxf>`_ (DXF) may be opened online with `Autodesk Viewer <https://viewer.autodesk.com/>`_
-* `ESP32 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ (PDF) 
+* `ESP32 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ (PDF)
 * `ESP32-WROVER-E Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32-wrover-e_esp32-wrover-ie_datasheet_en.pdf>`_ (PDF)
 * :doc:`../../api-guides/jtag-debugging/index`
 * :doc:`../../hw-reference/index`

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

@@ -1195,6 +1195,7 @@ ESP-IDF 构建属性
 - COMPILE_DEFINITIONS - 适用于所有组件源文件的编译定义。
 - CXX_COMPILE_OPTIONS - 适用于所有组件的 C++ 源文件的编译选项。
 - EXECUTABLE - 项目可执行文件；通过调用 ``idf_build_executable`` 设置。
+- DEPENDENCIES_LOCK - 组件管理器使用的依赖关系锁定文件的路径。默认值为项目路径下的 `dependencies.lock`。
 - EXECUTABLE_NAME - 不含扩展名的项目可执行文件的名称；通过调用 ``idf_build_executable`` 设置。
 - EXECUTABLE_DIR - 输出的可执行文件的路径
 - IDF_COMPONENT_MANAGER - 默认启用组件管理器，但如果设置这个属性为`0``，则会被 IDF_COMPONENT_MANAGER 环境变量禁用。
@@ -1362,7 +1363,7 @@ JSON 配置服务器
 
 您可以通过 ``idf.py confserver`` 或 ``ninja kconfserver`` 从项目中运行 ``kconfserver``，也可以使用不同的构建生成器来触发类似的目标。
 
-有关 kconfserver 的更多信息，请参阅 `esp-idf-kconfig documentation <https://github.com/espressif/esp-idf-kconfig/blob/master/docs/DOCUMENTATION.md>`_.
+有关 kconfserver 的更多信息，请参阅 `esp-idf-kconfig 文档 <https://github.com/espressif/esp-idf-kconfig/blob/master/docs/DOCUMENTATION.md>`_。
 
 构建系统内部
 =======================

docs/zh_CN/api-guides/dfu.rst

@@ -128,3 +128,10 @@ USB 驱动（仅限 Windows）
 - 出现 ``No DFU capable USB device available`` 错误的原因可能是在 Windows 上没有正确安装 USB 驱动程序（请参考 :ref:`api_guide_dfu_flash_win`），或是未在 Linux 上设置 Udev 规则（请参考 :ref:`api_guide_dfu_flash_udev`)，或是设备未处于引导加载程序模式。
 
 - 在 Windows 上使用 ``dfu-util`` 第一次烧录失败，并出现 ``Lost device after RESET?`` 错误信息。出现此问题时，请重新烧录一次，再次烧录应该会成功。
+
+.. only:: SOC_SUPPORTS_SECURE_DL_MODE
+
+    安全下载模式
+    --------------------
+
+    启用安全下载模式后，DFU 不再可用。请参见 :doc:`Flash 加密 <../security/flash-encryption>`，了解详细信息。

docs/zh_CN/api-guides/fatal-errors.rst

@@ -79,6 +79,8 @@
 
   如果使能了该选项，紧急处理程序的代码（包括所需的 UART 函数）会放置在 IRAM 中，导致 SRAM 中的可用内存空间变小。当禁用 flash 高速缓存（如写入 SPI flash）时或触发异常导致 flash 高速缓存崩溃时，可用此选项调试一些复杂的崩溃问题。
 
+- 如果启用 :ref:`CONFIG_ESP_SYSTEM_PANIC_REBOOT_DELAY_SECONDS` （默认为禁用）并将其配置为大于 0 的数字，紧急处理程序将基于该数字延迟重启的时间，单位为秒。如果用于监测串行输出的工具不支持停止和检查串行输出，可启用该选项。在这种情况下，借助延迟重启，用户可以在延迟期间检查和调试紧急处理程序的输出（例如回溯）。延迟结束后，设备将重新启动，并记录重置原因。
+
 下图展示了紧急处理程序的行为：
 
 .. blockdiag::

docs/zh_CN/api-guides/unit-tests.rst

@@ -219,11 +219,8 @@ DUT2（slave）终端::
 可以输入以下任意一项来运行测试用例：
 
 -  引号中写入测试用例的名字，运行单个测试用例。
-
 -  测试用例的序号，运行单个测试用例。
-
 -  方括号中的模块名字，运行指定模块所有的测试用例。
-
 -  星号，运行所有测试用例。
 
 ``[multi_device]`` 和 ``[multi_stage]``标签告诉测试运行者该用例是多设备测试还是多阶段测试。这些标签由 ``TEST_CASE_MULTIPLE_STAGES`` 和 ``TEST_CASE_MULTIPLE_DEVICES`` 宏自动生成。
@@ -311,7 +308,9 @@ Mocks
 对组件进行 Mock
 ^^^^^^^^^^^^^^^^
 
-要创建组件的 Mock 版本（也称为 “组件模拟”），需要以特定方式覆盖组件。覆盖组件时需要创建一个与原始组件名称完全相同的组件，然后让构建系统先发现原始组件再发现这个具有相同名称的新组件。具体可参考 :ref:`同名组件 <cmake-components-same-name>`。
+如果 ESP-IDF 中已对组件进行 Mock（也称为 *组件模拟*），那么只要满足要求，该版本即可立即投入使用。已进行 Mock 的组件列表，可参考 :ref:`component-linux-mock-support`。具体组件模拟的使用方法，请参考 :ref:`adjustments_for_mocks`。
+
+如果 ESP-IDF 尚未提供任何组件模拟，则需要创建组件的 Mock 版本，以特定方式覆盖组件。覆盖组件时，需要创建一个与原始组件名称完全相同的组件，让构建系统先发现原始组件，再发现这个具有相同名称的新组件。具体可参考 :ref:`同名组件 <cmake-components-same-name>`。
 
 在组件模拟中需要指定如下部分：
 
@@ -345,6 +344,12 @@ Mocks
 
 可在 IDF 目录的 :idf:`tools/mocks` 下找到组件模拟的示例。有关如何 *覆盖 IDF 组件*，可查看 :ref:`同名组件 <cmake-components-same-name>`。
 
+- :component_file:`NVS 页面类的单元测试 <nvs_flash/host_test/nvs_page_test/README.md>`。
+- :component_file:`esp_event 的单元测试 <esp_event/host_test/esp_event_unit_test/main/esp_event_test.cpp>`。
+- :component_file:`mqtt 的单元测试 <mqtt/esp-mqtt/host_test/README.md>`。
+
+.. _adjustments_for_mocks:
+
 修改单元测试文件
 ^^^^^^^^^^^^^^^^^^^^^^^^
 

docs/zh_CN/hw-reference/esp32/get-started-wrover-kit.rst

@@ -246,12 +246,12 @@ JP1 连接器包括 14 x 2 个排针，具体功能可见下表中间 “I/O”
 说明：
 
 * NC/XTAL - :ref:`32.768 kHz 晶振 <get-started-esp-wrover-kit-v4.1-xtal>`
-* JTAG - :ref:`JTAG / JP2 <get-started-esp-wrover-kit-v4.1-jtag-header>`
-* Boot - Boot 按键 / SW2
-* 摄像头 - :ref:`摄像头 / JP4 <get-started-esp-wrover-kit-v4.1-camera-header>`
+* JTAG - :ref:`JTAG/JP2 <get-started-esp-wrover-kit-v4.1-jtag-header>`
+* Boot - Boot 按键/SW2
+* 摄像头 - :ref:`摄像头/JP4 <get-started-esp-wrover-kit-v4.1-camera-header>`
 * LED - :ref:`RGB LED <get-started-esp-wrover-kit-v4.1-rgb-led-connections>`
-* microSD - :ref:`microSD Card / J4 <get-started-esp-wrover-kit-v4.1-microsd-card-slot>`
-* LCD - :ref:`LCD / U5 <get-started-esp-wrover-kit-v4.1-lcd-connector>`
+* microSD - :ref:`microSD Card/J4 <get-started-esp-wrover-kit-v4.1-microsd-card-slot>`
+* LCD - :ref:`LCD/U5 <get-started-esp-wrover-kit-v4.1-lcd-connector>`
 * PSRAM - ESP32-WROVER-E 的 PSRAM
 
 
@@ -274,20 +274,24 @@ JP1 连接器包括 14 x 2 个排针，具体功能可见下表中间 “I/O”
 
 .. _get-started-esp-wrover-kit-v4.1-spi-flash-header:
 
-SPI Flash / JP2
+SPI Flash/JP2
 ^^^^^^^^^^^^^^^
 
 ====  =============
 .     ESP32 管脚
 ====  =============
-1     CLK / GPIO6
-2     SD0 / GPIO7
-3     SD1 / GPIO8
-4     SD2 / GPIO9
-5     SD3 / GPIO10
-6     CMD / GPIO11
+1     CLK/GPIO6
+2     SD0/GPIO7
+3     SD1/GPIO8
+4     SD2/GPIO9
+5     SD3/GPIO10
+6     CMD/GPIO11
 ====  =============
 
+.. note::
+
+    SPI Flash 管脚用于访问内部闪存。因此，这些管脚不支持连接外部 SPI 设备，仅用于监测或高级选项。
+
 .. important::
 
     模组的 flash 总线已通过 0 欧电阻 R140 ~ R145 连接至排针 JP2。如果需要将 flash 的工作频率控制在 80 MHz，以达到保证总线信号完整性等目的，建议移除 R140 ~ R145 电阻，将模组的 flash 总线与排针 JP2 断开。
@@ -295,23 +299,23 @@ SPI Flash / JP2
 
 .. _get-started-esp-wrover-kit-v4.1-jtag-header:
 
-JTAG / JP2
+JTAG/JP2
 ^^^^^^^^^^
 
 ====  ==============  =============
 .     ESP32 管脚       JTAG 信号
 ====  ==============  =============
 1     EN              TRST_N
-2     MTMS / GPIO14   TMS
-3     MTDO / GPIO15   TDO
-4     MTDI / GPIO12   TDI
-5     MTCK / GPIO13   TCK
+2     MTMS/GPIO14     TMS
+3     MTDO/GPIO15     TDO
+4     MTDI/GPIO12     TDI
+5     MTCK/GPIO13     TCK
 ====  ==============  =============
 
 
 .. _get-started-esp-wrover-kit-v4.1-camera-header:
 
-摄像头 / JP4
+摄像头/JP4
 ^^^^^^^^^^^^
 
 ====  ==========  =============================
@@ -319,22 +323,22 @@ JTAG / JP2
 ====  ==========  =============================
 1     n/a         3.3V
 2     n/a         地
-3     GPIO27      SIO_C / SCCB 时钟
-4     GPIO26      SIO_D / SCCB 数据
-5     GPIO25      VSYNC / 垂直同步
-6     GPIO23      HREF / 水平参考
-7     GPIO22      PCLK / 像素时钟
-8     GPIO21      XCLK / 系统时钟
-9     GPIO35      D7 / 像素数据 Bit 7
-10    GPIO34      D6 / 像素数据 Bit 6
-11    GPIO39      D5 / 像素数据 Bit 5
-12    GPIO36      D4 / 像素数据 Bit 4
-13    GPIO19      D3 / 像素数据 Bit 3
-14    GPIO18      D2 / 像素数据 Bit 2
-15    GPIO5       D1 / 像素数据 Bit 1
-16    GPIO4       D0 / 像素数据 Bit 0
-17    GPIO0       RESET / 摄像头复位
-18    n/a         PWDN / 摄像头断电
+3     GPIO27      SIO_C/SCCB 时钟
+4     GPIO26      SIO_D/SCCB 数据
+5     GPIO25      VSYNC/垂直同步
+6     GPIO23      HREF/水平参考
+7     GPIO22      PCLK/像素时钟
+8     GPIO21      XCLK/系统时钟
+9     GPIO35      D7/像素数据 Bit 7
+10    GPIO34      D6/像素数据 Bit 6
+11    GPIO39      D5/像素数据 Bit 5
+12    GPIO36      D4/像素数据 Bit 4
+13    GPIO19      D3/像素数据 Bit 3
+14    GPIO18      D2/像素数据 Bit 2
+15    GPIO5       D1/像素数据 Bit 1
+16    GPIO4       D0/像素数据 Bit 0
+17    GPIO0       RESET/摄像头复位
+18    n/a         PWDN/摄像头断电
 ====  ==========  =============================
 
 * D0 到 D7 为摄像头的数据总线
@@ -362,10 +366,10 @@ microSD 卡
 ====  ==============  ===============
 .     ESP32 管脚       microSD 信号
 ====  ==============  ===============
-1.    MTDI / GPIO12   DATA2
-2.    MTCK / GPIO13   CD / DATA3
-3.    MTDO / GPIO15   CMD
-4.    MTMS / GPIO14   CLK
+1.    MTDI/GPIO12     DATA2
+2.    MTCK/GPIO13     CD/DATA3
+3.    MTDO/GPIO15     CMD
+4.    MTMS/GPIO14     CLK
 5.    GPIO2           DATA0
 6.    GPIO4           DATA1
 7.    GPIO21          Card Detect
@@ -374,7 +378,7 @@ microSD 卡
 
 .. _get-started-esp-wrover-kit-v4.1-lcd-connector:
 
-LCD / U5
+LCD/U5
 ^^^^^^^^
 
 ====  ==============  ===============
@@ -436,7 +440,7 @@ USB 供电                   使能 UART 通信
 
 * `ESP-WROVER-KIT V4.1 原理图`_ (PDF)
 * `ESP-WROVER-KIT V4.1 布局 <https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_V4.1.dxf>`_ (DXF)
-* `《ESP32 技术规格书》 <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ (PDF) 
+* `《ESP32 技术规格书》 <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ (PDF)
 * `《ESP32-WROVER-E 技术规格书》 <https://www.espressif.com/sites/default/files/documentation/esp32-wrover-e_esp32-wrover-ie_datasheet_cn.pdf>`_ (PDF)
 * :doc:`../../api-guides/jtag-debugging/index`
 * :doc:`../../hw-reference/index`