doc: fix broken .. only:: in JTAG guide

Added note about .. only:: limitations to guide

docs/en/api-guides/jtag-debugging/tips-and-quirks.rst

@@ -69,9 +69,10 @@ FreeRTOS support
 OpenOCD has explicit support for the ESP-IDF FreeRTOS. GDB can see FreeRTOS tasks as threads. Viewing them all can be done using the GDB ``i threads`` command, changing to a certain task is done with ``thread n``, with ``n`` being the number of the thread. FreeRTOS detection can be disabled in target's configuration. For more details see :ref:`jtag-debugging-tip-openocd-configure-target`.
 
 
-.. _jtag-debugging-tip-code-flash-voltage:
 
-.. only:: esp33
+.. only:: esp32
+
+    .. _jtag-debugging-tip-code-flash-voltage:
 
     Why to set SPI flash voltage in OpenOCD configuration?
     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -83,7 +84,11 @@ OpenOCD has explicit support for the ESP-IDF FreeRTOS. GDB can see FreeRTOS task
     Check specification of ESP32 module connected to JTAG, what is the power supply voltage of SPI flash chip. Then set ``ESP32_FLASH_VOLTAGE`` accordingly. Most WROOM modules use 3.3 V flash, while WROVER modules use 1.8 V flash.
 
 
-.. _jtag-debugging-tip-optimize-jtag-speed:
+    .. _jtag-debugging-tip-optimize-jtag-speed:
+
+.. only:: esp32s2
+
+    .. _jtag-debugging-tip-optimize-jtag-speed:
 
 Optimize JTAG speed
 ^^^^^^^^^^^^^^^^^^^
@@ -156,19 +161,18 @@ Disable RTOS support
 
 Comment out this line to have RTOS support.
 
-
-Power supply voltage of ESP32's SPI flash chip
-""""""""""""""""""""""""""""""""""""""""""""""
-
-::
-
-    set ESP32_FLASH_VOLTAGE 1.8
-
-Comment out this line to set 3.3 V, ref: :ref:`jtag-debugging-tip-code-flash-voltage`
-
-
 .. only:: esp32
 
+    Power supply voltage of ESP32's SPI flash chip
+    """"""""""""""""""""""""""""""""""""""""""""""
+
+    ::
+
+        set ESP32_FLASH_VOLTAGE 1.8
+
+    Comment out this line to set 3.3 V, ref: :ref:`jtag-debugging-tip-code-flash-voltage`
+
+
     Configuration file for ESP32 targets
     """"""""""""""""""""""""""""""""""""
 

docs/en/contribute/documenting-code.rst

@@ -255,7 +255,7 @@ Exclusion of content based on chip-target
 Occasionally there will be content that is only relevant for one of targets. When this is the case, you can exclude that content by using the ''.. only:: TARGET'' directive, where you replace 'TARGET' with one of the chip names. As of now the following targets are available:
 
 * esp32
-* esp32s2 
+* esp32s2
 
 Example:
 
@@ -267,7 +267,30 @@ Example:
 
 This functionality is provided by the `Sphinx selective exclude <https://github.com/pfalcon/sphinx_selective_exclude>`_ extension.
 
-The '':TARGET:'' role is used for excluding content from a table of content tree. For example:
+A weakness in this extension is that it does not correctly handle the case were you exclude a section, and that is directly followed by a labeled new section. In these cases everything will render correctly, but the label will not correctly link to the section that follows. A temporary work-around for the cases were this can't be avoided is the following:
+
+.. code-block:: none
+
+    .. only:: esp32
+
+        .. _section_1_label:
+
+        Section 1
+        ^^^^^^^^^
+
+        Section one content
+
+        .. _section_2_label:
+
+    .. only:: esp32s2
+
+        _section_2_label:
+
+    Section 2
+    ^^^^^^^^^
+    Section 2 content
+
+The :TARGET: role is used for excluding content from a table of content tree. For example:
 
 .. code-block:: none
 

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

@@ -276,19 +276,10 @@ Windows 用户::
 
 本节列出了本指南中提到的所有注意事项和补充内容的链接。
 
-* :ref:`jtag-debugging-tip-breakpoints`
-* :ref:`jtag-debugging-tip-where-breakpoints`
-* :ref:`jtag-debugging-tip-flash-mappings`
-* :ref:`jtag-debugging-tip-why-next-works-as-step`
-* :ref:`jtag-debugging-tip-code-options`
-* :ref:`jtag-debugging-tip-freertos-support`
-* :ref:`jtag-debugging-tip-code-flash-voltage`
-* :ref:`jtag-debugging-tip-optimize-jtag-speed`
-* :ref:`jtag-debugging-tip-debugger-startup-commands`
-* :ref:`jtag-debugging-tip-openocd-configure-target`
-* :ref:`jtag-debugging-tip-reset-by-debugger`
-* :ref:`jtag-debugging-tip-jtag-pins-reconfigured`
-* :ref:`jtag-debugging-tip-reporting-issues`
+.. toctree::
+    :maxdepth: 2
+
+    tips-and-quirks
 
 
 相关文档

docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst

@@ -67,10 +67,9 @@ ESP-IDF 有一些针对 OpenOCD 调试功能的选项可以在编译时进行设
 
 OpenOCD 完全支持 ESP-IDF 自带的 FreeRTOS 操作系统，GDB 会将 FreeRTOS 中的任务当做线程。使用 GDB 命令 ``i threads`` 可以查看所有的线程，使用命令 ``thread n`` 可以切换到某个具体任务的堆栈，其中 ``n`` 是线程的编号。检测 FreeRTOS 的功能可以在配置目标时被禁用。更多详细信息，请参阅 :ref:`jtag-debugging-tip-openocd-configure-target`.
 
+.. only:: esp32
 
-.. _jtag-debugging-tip-code-flash-voltage:
-
-.. only:: esp33
+    .. _jtag-debugging-tip-code-flash-voltage:
 
     在 OpenOCD 的配置文件中设置 SPI 闪存的工作电压
     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -81,8 +80,11 @@ OpenOCD 完全支持 ESP-IDF 自带的 FreeRTOS 操作系统，GDB 会将 FreeRT
 
     查看 JTAG 连接的 ESP32 模组的规格书，检查其 SPI 闪存芯片的供电电压值，然后再相应的设置 ``ESP32_FLASH_VOLTAGE``。大多数的 WROOM 模组使用 3.3 V 的闪存芯片，但是 WROVER 模组使用 1.8 V 的闪存芯片。
 
+    .. _jtag-debugging-tip-optimize-jtag-speed:
 
-.. _jtag-debugging-tip-optimize-jtag-speed:
+.. only:: esp32s2
+
+    .. _jtag-debugging-tip-optimize-jtag-speed:
 
 优化 JTAG 的速度
 ^^^^^^^^^^^^^^^^
@@ -156,24 +158,23 @@ OpenOCD 需要知道当前使用的 JTAG 适配器的类型，以及其连接的
 
 如果要支持 RTOS， 请注释掉这一行。
 
-
-ESP32 的 SPI 闪存芯片的电源电压
-"""""""""""""""""""""""""""""""
-
-::
-
-    set ESP32_FLASH_VOLTAGE 1.8
-
-如果 SPI 闪存芯片的电源电压为 3.3 V， 请注释掉这一行，更多信息请参阅： :ref:`jtag-debugging-tip-code-flash-voltage`。
-
-
-
-
-ESP32 的目标配置文件
-""""""""""""""""""""
-
 .. only:: esp32
 
+    ESP32 的 SPI 闪存芯片的电源电压
+    """"""""""""""""""""""""""""""""""
+
+    ::
+
+        set ESP32_FLASH_VOLTAGE 1.8
+
+    如果 SPI 闪存芯片的电源电压为 3.3 V， 请注释掉这一行，更多信息请参阅： :ref:`jtag-debugging-tip-code-flash-voltage`。
+
+
+
+
+    ESP32 的目标配置文件
+    """"""""""""""""""""
+
     ::
 
         source [find target/esp32.cfg]