doc: EN doc update and fixed warnings

2025-08-02 12:14:32 +02:00 · 2019-12-10 11:58:00 +08:00
parent e06a57f34f
commit d56ea52ea1
13 changed files with 345 additions and 351 deletions
--- a/docs/conf_common.py
+++ b/docs/conf_common.py
@@ -133,8 +133,8 @@ def update_exclude_patterns(tags):
                  'api-guides/ulp-legacy.rst',
                  'api-guides/unit-tests-legacy.rst',
                  'api-guides/jtag-debugging/configure-wrover.rst',
-                  'api-reference/bluetooth/**',
                  'api-reference/system/himem.rst',
+                  'api-reference/bluetooth/**',
                  'api-reference/system/ipc.rst',
                  'hw-reference/get-started-devkitc-v2.rst',
                  'hw-reference/get-started-devkitc.rst',
@@ -149,7 +149,6 @@ def update_exclude_patterns(tags):
                  'gnu-make-legacy.rst']:
            exclude_patterns.append(e)

-
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
 # default_role = None
--- a/docs/en/api-guides/external-ram.rst
+++ b/docs/en/api-guides/external-ram.rst
@@ -19,6 +19,8 @@ Hardware

 The ESP-PSRAM32 chip is a 1.8 V device which can only be used in parallel with a 1.8 V flash component. Make sure to either set the MTDI pin to a high signal level on bootup, or program {IDF_TARGET_NAME} eFuses to always use the VDD_SIO level of 1.8 V. Not doing this can damage the PSRAM and/or flash chip.

+.. only:: esp32
+
    To connect the ESP-PSRAM32 chip to ESP32D0W*, connect the following signals:

    * PSRAM /CE (pin 1) > ESP32 GPIO 16
--- a/docs/en/api-guides/freertos-smp.rst
+++ b/docs/en/api-guides/freertos-smp.rst
@@ -64,7 +64,7 @@ to ESP-IDF.
  not done so already. Furthermore, ``float`` cannot be used in interrupt service
  routines.

-:ref:`task-deletion`: Task deletion behavior has been backported from FreeRTOS
+`Task Deletion`_: Task deletion behavior has been backported from FreeRTOS
 v9.0.0 and modified to be SMP compatible. Task memory will be freed immediately
 when :cpp:func:`vTaskDelete` is called to delete a task that is not currently running
 and not pinned to the other core. Otherwise, freeing of task memory will still
@@ -461,7 +461,7 @@ occur.
 ESP-IDF FreeRTOS provides the added feature of Deletion Callbacks. Deletion
 Callbacks are called automatically during task deletion to free memory pointed
 to by TLSP. Each TLSP can have its own Deletion Callback. Note that due to the
-to :ref:`task-deletion` behavior, there can be instances where Deletion
+to `Task Deletion`_ behavior, there can be instances where Deletion
 Callbacks are called in the context of the Idle Tasks. Therefore Deletion
 Callbacks **should never attempt to block** and critical sections should be kept
 as short as possible to minimize priority inversion.
--- a/docs/en/api-guides/jtag-debugging/index.rst
+++ b/docs/en/api-guides/jtag-debugging/index.rst
@@ -150,7 +150,7 @@ Open a terminal and set it up for using the ESP-IDF as described in the :ref:`se

 .. note::

-    The files provided after ``-f`` above are specific for ESP-WROVER-KIT with :ref:`esp-modules-and-boards-esp32-wroom-32` module. You may need to provide different files depending on used hardware. For guidance see :ref:`jtag-debugging-tip-openocd-configure-target`.
+    The files provided after ``-f`` above are specific for ESP-WROVER-KIT with esp32-wroom-32 module. You may need to provide different files depending on used hardware. For guidance see :ref:`jtag-debugging-tip-openocd-configure-target`.

 .. highlight:: none

--- a/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst
+++ b/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst
@@ -103,7 +103,7 @@ What is the meaning of debugger's startup commands?

 On startup, debugger is issuing sequence of commands to reset the chip and halt it at specific line of code. This sequence (shown below) is user defined to pick up at most convenient / appropriate line and start debugging.

-* ``set remote hardware-watchpoint-limit 2`` — Restrict GDB to using two hardware watchpoints supported by the chip, 2 for ESP32. For more information see https://sourceware.org/gdb/onlinedocs/gdb/Remote-Configuration.html.
+* ``set remote hardware-watchpoint-limit 2`` — Restrict GDB to using two hardware watchpoints supported by the chip, 2 for {IDF_TARGET_NAME}. For more information see https://sourceware.org/gdb/onlinedocs/gdb/Remote-Configuration.html.
 * ``mon reset halt`` — reset the chip and keep the CPUs halted
 * ``flushregs`` — monitor (``mon``) command can not inform GDB that the target state has changed. GDB will assume that whatever stack the target had before ``mon reset halt`` will still be valid. In fact, after reset the target state will change, and executing ``flushregs`` is a way to force GDB to get new state from the target.
 * ``thb app_main`` — insert a temporary hardware breakpoint at ``app_main``, put here another function name if required
@@ -117,7 +117,7 @@ Configuration of OpenOCD for specific target

 OpenOCD needs to be told what JTAG adapter to use and processor the JTAG adapter is connected to. To do so, use existing **board** configuration files located in OpenOCD's ``share/openocd/scripts/board`` folder.

-For example, if you connect to ESP-WROVER-KIT with ESP-WROOM-32 module installed (see section :ref:`esp-modules-and-boards-esp-wrover-kit-v1`), use the following configuration files:
+For example, if you connect to ESP-WROVER-KIT with ESP-WROOM-32 module installed, use the following configuration files:

 * ``board/esp32-wrover-kit-3.3v.cfg``

@@ -135,6 +135,7 @@ Adapter's clock speed

 See :ref:`jtag-debugging-tip-optimize-jtag-speed` for guidance how to set this value.

+.. only:: esp32

    Single core debugging
    """""""""""""""""""""
--- a/docs/en/api-reference/peripherals/rmt.rst
+++ b/docs/en/api-reference/peripherals/rmt.rst
@@ -242,7 +242,7 @@ The RMT controller triggers interrupts on four specific events describes below.

 Setting or clearing an interrupt enable mask for specific channels and events may be also done by calling :cpp:func:`rmt_set_intr_enable_mask` or :cpp:func:`rmt_clr_intr_enable_mask`.

-When servicing an interrupt within an ISR, the interrupt need to explicitly cleared. To do so, set specific bits described as ``RMT.int_clr.val.chN_event_name`` and defined as a ``volatile struct`` in :component_file:`soc/{IDT_TARGET_PATH_NAME}/include/soc/rmt_struct.h`, where N is the RMT channel number [0, 7] and the ``event_name`` is one of four events described above.
+When servicing an interrupt within an ISR, the interrupt need to explicitly cleared. To do so, set specific bits described as ``RMT.int_clr.val.chN_event_name`` and defined as a ``volatile struct`` in :component_file:`soc/{IDF_TARGET_PATH_NAME}/include/soc/rmt_struct.h`, where N is the RMT channel number [0, 7] and the ``event_name`` is one of four events described above.

 If you do not need an ISR anymore, you can deregister it by calling a function :cpp:func:`rmt_isr_deregister`.

--- a/docs/en/contribute/add-ons-reference.rst
+++ b/docs/en/contribute/add-ons-reference.rst
@@ -148,7 +148,7 @@ Other Extensions

 :idf_file:`docs/idf_extensions/format_idf_target.py`
    An extension for replacing generic target related names with the idf_target passed to the Sphinx command line.
-    This is a {\IDF_TARGET_NAME}, with /{\IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{\IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG{\IDF_TARGET_CFG_PREFIX}_MULTI_DOC` will, if the backspaces are removed, render as This is a {IDF_TARGET_NAME}, with /{IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG{IDF_TARGET_CFG_PREFIX}_MULTI_DOC`.
+    This is a {\IDF_TARGET_NAME}, with /{\IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{\IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG_{\IDF_TARGET_CFG_PREFIX}_MULTI_DOC` will, if the backspaces are removed, render as This is a {IDF_TARGET_NAME}, with /{IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG_{IDF_TARGET_CFG_PREFIX}_MULTI_DOC`.

    This cannot be used inside tables.

--- a/docs/en/hw-reference/index.rst
+++ b/docs/en/hw-reference/index.rst
@@ -3,27 +3,15 @@
 ************************************
 :link_to_translation:`zh_CN:[中文]`

-.. only:: esp32
-
 .. toctree::
    :maxdepth: 3

-        Technical Reference Manual (PDF) <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>
-        Datasheet (PDF) <https://espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>
-        Hardware Design Guidelines (PDF) <https://espressif.com/sites/default/files/documentation/esp32_hardware_design_guidelines_en.pdf>
-        Silicon Errata (PDF) <https://espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf>
-        Modules and Boards <modules-and-boards>
-        Previous Versions of Modules and Boards <modules-and-boards-previous>
-        Espressif Products Ordering Information (PDF) <http://www.espressif.com/sites/default/files/documentation/espressif_products_ordering_information_en.pdf>
-        Regulatory Certificates <https://www.espressif.com/en/certificates>
-
-.. only:: esp32s2beta
-
-    .. toctree::
-    :maxdepth: 3
-
-        Technical Reference Manual (PDF) <https://espressif.com/sites/default/files/documentation/esp32s2_technical_reference_manual_en.pdf>
-        Datasheet (PDF) <https://espressif.com/sites/default/files/documentation/esp32s2_datasheet_en.pdf>
+    :esp32: Technical Reference Manual (PDF) <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>
+    :esp32s2beta: Technical Reference Manual (PDF) <https://espressif.com/sites/default/files/documentation/esp32s2_technical_reference_manual_en.pdf>
+    :esp32: Datasheet (PDF) <https://espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>
+    :esp32s2beta: Datasheet (PDF) <https://espressif.com/sites/default/files/documentation/esp32s2_datasheet_en.pdf>
+    :esp32: Hardware Design Guidelines (PDF) <https://espressif.com/sites/default/files/documentation/esp32_hardware_design_guidelines_en.pdf>
+    :esp32: Silicon Errata (PDF) <https://espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf>
    Modules and Boards <modules-and-boards>
    Previous Versions of Modules and Boards <modules-and-boards-previous>
    Espressif Products Ordering Information (PDF) <http://www.espressif.com/sites/default/files/documentation/espressif_products_ordering_information_en.pdf>
--- a/docs/en/hw-reference/modules-and-boards-previous.rst
+++ b/docs/en/hw-reference/modules-and-boards-previous.rst
@@ -1,10 +1,10 @@
 .. _esp-modules-and-boards-previous:

-*********************************************
-Previous Versions of ESP32 Modules and Boards
-*********************************************
+*********************************************************
+Previous Versions of {IDF_TARGET_NAME} Modules and Boards
+*********************************************************

-This sections contains overview and links to documentation of previous version ESP32 Modules and Boards that have been replaced with newer versions or discontinued. It is maintained for convenience of users as previous versions of some modules and boards are still in use and some may still be available for purchase. 
+This sections contains overview and links to documentation of previous version {IDF_TARGET_NAME} Modules and Boards that have been replaced with newer versions or discontinued. It is maintained for convenience of users as previous versions of some modules and boards are still in use and some may still be available for purchase.


 Modules (No updated or discontinued modules)
@@ -18,6 +18,8 @@ Development Boards

 To see the latest development boards, please refer to section :ref:`esp-modules-and-boards`.

+.. only:: esp32
+
    .. _esp-modules-and-boards-esp32-pico-kit-v4:

    ESP32-PICO-KIT V4
--- a/docs/en/hw-reference/modules-and-boards.rst
+++ b/docs/en/hw-reference/modules-and-boards.rst
@@ -1,12 +1,12 @@
 .. _esp-modules-and-boards:

-************************
-ESP32 Modules and Boards
-************************
+************************************
+{IDF_TARGET_NAME} Modules and Boards
+************************************

 :link_to_translation:`zh_CN:[中文]`

-Espressif designs and manufactures different modules and development boards to help users evaluate the potential of the ESP32 family of chips.
+Espressif designs and manufactures different modules and development boards to help users evaluate the potential of the {IDF_TARGET_NAME} family of chips.

 This document provides description of modules and development boards currently available from Espressif.

@@ -19,10 +19,12 @@ This document provides description of modules and development boards currently a
 Modules
 =======

-This is a family of ESP32-based modules with some integrated key components, including a crystal oscillator and an antenna matching circuit. The modules constitute ready-made solutions for integration into final products. If combined with a few extra components, such as a programming interface, bootstrapping resistors, and pin headers, these modules can also be used for evaluation of ESP32's functionality.
+This is a family of {IDF_TARGET_NAME}-based modules with some integrated key components, including a crystal oscillator and an antenna matching circuit. The modules constitute ready-made solutions for integration into final products. If combined with a few extra components, such as a programming interface, bootstrapping resistors, and pin headers, these modules can also be used for evaluation of {IDF_TARGET_NAME}'s functionality.

 The key characteristics of these modules are summarized in the table below. Some additional details are covered in the following sections.

+.. only:: esp32
+
    ===================  ============  ===========  =========  ====  ===============
    Module               Chip          Flash, MB    PSRAM, MB  Ant.  Dimensions, mm
    ===================  ============  ===========  =========  ====  ===============