docs: Add "explicit only" directive & use only:: to block out some chip-specific parts of docs

docs/build_docs.py

@@ -73,6 +73,7 @@ def build_docs(language, target, build_dir):
                 "-d", os.path.join(build_dir, "doctrees"),
                 # TODO: support multiple sphinx-warning.log files, somehow
                 "-w", "sphinx-warning.log",
+                "-t", target,
                 "-D", "idf_target={}".format(target),
                 os.path.join(os.path.abspath(os.path.dirname(__file__)), language), # srcdir for this language
                 os.path.join(build_dir, "html")                    # build directory

docs/conf_common.py

@@ -105,6 +105,10 @@ extensions = ['breathe',
               'doxygen_idf',
               'sphinx.ext.todo',
               'include_build_file',
+              # from https://github.com/pfalcon/sphinx_selective_exclude
+              'sphinx_selective_exclude.eager_only',
+              #'sphinx_selective_exclude.search_auto_exclude',
+              #'sphinx_selective_exclude.modindex_exclude',
               ]
 
 # sphinx.ext.todo extension parameters

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

@@ -883,7 +883,9 @@ the ESP-IDF build system entirely by using a CMake feature called ExternalProjec
 - 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.
 - Finally, the generated library is added to `ADDITIONAL_MAKE_CLEAN_FILES`_. This means ``make clean`` will delete this library. (Note that the other object files from the build won't be deleted.)
 
-.. note:: When using an external build process with PSRAM, remember to add ``-mfix-esp32-psram-cache-issue`` to the C compiler arguments. See :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND` for details of this flag.
+.. only:: esp32
+
+   .. note:: When using an external build process with PSRAM, remember to add ``-mfix-esp32-psram-cache-issue`` to the C compiler arguments. See :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND` for details of this flag.
 
 .. _ADDITIONAL_MAKE_CLEAN_FILES_note:
 
@@ -1108,7 +1110,10 @@ It is possible to do so by using the :ref:`build system APIs provided<cmake_buil
 The example in :example:`build_system/cmake/idf_as_lib` demonstrates the creation of an application equivalent to :example:`hello world application <get-started/hello_world>`
 using a custom CMake project.
 
-.. note:: The IDF build system can only set compiler flags for source files that it builds. When an external CMakeLists.txt file is used and PSRAM is enabled, remember to add ``-mfix-esp32-psram-cache-issue`` to the C compiler arguments. See :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND` for details of this flag.
+.. only:: esp32
+
+   .. note:: The IDF build system can only set compiler flags for source files that it builds. When an external CMakeLists.txt file is used and PSRAM is enabled, remember to add ``-mfix-esp32-psram-cache-issue`` to the C compiler arguments. See :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND` for details of this flag.
+
 .. _cmake_buildsystem_api:
 
 ESP-IDF CMake Build System API

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

@@ -58,7 +58,13 @@ Subsequent behavior of the panic handler can be set using :ref:`CONFIG_ESP32_PAN
 
 Behavior of panic handler is affected by two other configuration options.
 
-- If :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` is enabled (which is the default), panic handler will detect whether a JTAG debugger is connected. If it is, execution will be halted and control will be passed to the debugger. In this case registers and backtrace are not dumped to the console, and GDBStub / Core Dump functions are not used.
+.. only:: esp32
+
+    - If :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` is enabled (which is the default), panic handler will detect whether a JTAG debugger is connected. If it is, execution will be halted and control will be passed to the debugger. In this case registers and backtrace are not dumped to the console, and GDBStub / Core Dump functions are not used.
+
+.. only:: esp32s2beta
+
+    - If :ref:`CONFIG_ESP32S2_DEBUG_OCDAWARE` is enabled (which is the default), panic handler will detect whether a JTAG debugger is connected. If it is, execution will be halted and control will be passed to the debugger. In this case registers and backtrace are not dumped to the console, and GDBStub / Core Dump functions are not used.
 
 - If :doc:`Core Dump <core_dump>` feature is enabled (``CONFIG_ESP32_ENABLE_COREDUMP_TO_FLASH`` or ``CONFIG_ESP32_ENABLE_COREDUMP_TO_UART`` options), then system state (task stacks and registers) will be dumped either to Flash or UART, for later analysis.
 

docs/en/api-reference/system/power_management.rst

@@ -31,7 +31,13 @@ Dynamic frequency scaling (DFS) and automatic light sleep can be enabled in an a
 - ``min_freq_mhz``: Minimum CPU frequency in MHz, i.e., the frequency used when only the ``ESP_PM_APB_FREQ_MAX`` lock is acquired. This field can be set to the XTAL frequency value, or the XTAL frequency divided by an integer. Note that 10 MHz is the lowest frequency at which the default REF_TICK clock of 1 MHz can be generated.
 - ``light_sleep_enable``: Whether the system should automatically enter light sleep when no locks are acquired (``true``/``false``).
 
-Alternatively, if you enable the option :ref:`CONFIG_PM_DFS_INIT_AUTO` in menuconfig, the maximum CPU frequency will be determined by the :ref:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ` setting, and the minimum CPU frequency will be locked to the XTAL frequency.
+.. only:: esp32
+
+    Alternatively, if you enable the option :ref:`CONFIG_PM_DFS_INIT_AUTO` in menuconfig, the maximum CPU frequency will be determined by the :ref:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ` setting, and the minimum CPU frequency will be locked to the XTAL frequency.
+
+.. only:: esp32s2beta
+
+    Alternatively, if you enable the option :ref:`CONFIG_PM_DFS_INIT_AUTO` in menuconfig, the maximum CPU frequency will be determined by the :ref:`CONFIG_ESP32S2_DEFAULT_CPU_FREQ_MHZ` setting, and the minimum CPU frequency will be locked to the XTAL frequency.
 
 .. note::
 

docs/en/api-reference/system/system.rst

@@ -105,13 +105,15 @@ If the universally administered MAC addresses are not enough for all of the netw
 
 See `this article <https://en.wikipedia.org/wiki/MAC_address#Universal_vs._local>`_ for the definition of local and universally administered MAC addresses.
 
-The number of universally administered MAC address can be configured using :ref:`CONFIG_ESP32_UNIVERSAL_MAC_ADDRESSES` for ESP32.
+.. only:: esp32
 
-If the number of universal MAC addresses is two, only two interfaces (Wi-Fi Station and Bluetooth) receive a universally administered MAC address. These are generated sequentially by adding 0 and 1 (respectively) to the base MAC address. The remaining two interfaces (Wi-Fi SoftAP and Ethernet) receive local MAC addresses. These are derived from the universal Wi-Fi station and Bluetooth MAC addresses, respectively.
+    The number of universally administered MAC address can be configured using :ref:`CONFIG_ESP32_UNIVERSAL_MAC_ADDRESSES`.
 
-If the number of universal MAC addresses is four, all four interfaces (Wi-Fi Station, Wi-Fi SoftAP, Bluetooth and Ethernet) receive a universally administered MAC address. These are generated sequentially by adding 0, 1, 2 and 3 (respectively) to the final octet of the base MAC address.
+    If the number of universal MAC addresses is two, only two interfaces (Wi-Fi Station and Bluetooth) receive a universally administered MAC address. These are generated sequentially by adding 0 and 1 (respectively) to the base MAC address. The remaining two interfaces (Wi-Fi SoftAP and Ethernet) receive local MAC addresses. These are derived from the universal Wi-Fi station and Bluetooth MAC addresses, respectively.
 
-When using the default (Espressif-assigned) base MAC address, either setting can be used. When using a custom universal MAC address range, the correct setting will depend on the allocation of MAC addresses in this range (either 2 or 4 per device.)
+    If the number of universal MAC addresses is four, all four interfaces (Wi-Fi Station, Wi-Fi SoftAP, Bluetooth and Ethernet) receive a universally administered MAC address. These are generated sequentially by adding 0, 1, 2 and 3 (respectively) to the final octet of the base MAC address.
+
+    When using the default (Espressif-assigned) base MAC address, either setting can be used. When using a custom universal MAC address range, the correct setting will depend on the allocation of MAC addresses in this range (either 2 or 4 per device.)
 
 .. todo::
 

docs/en/get-started/index.rst

@@ -463,19 +463,21 @@ After startup and diagnostic logs scroll up, you should see "Hello world!" print
 
 To exit IDF monitor use the shortcut ``Ctrl+]``.
 
-If IDF monitor fails shortly after the upload, or, if instead of the messages above, you see random garbage similar to what is given below, your board is likely using a 26MHz crystal. Most development board designs use 40MHz, so ESP-IDF uses this frequency as a default value.
+.. only:: esp32
 
-.. figure:: ../../_static/get-started-garbled-output.png
-    :align: center
-    :alt: Garbled output
-    :figclass: align-center
+    If IDF monitor fails shortly after the upload, or, if instead of the messages above, you see random garbage similar to what is given below, your board is likely using a 26MHz crystal. Most development board designs use 40MHz, so ESP-IDF uses this frequency as a default value.
 
-If you have such a problem, do the following:
-
-1. Exit the monitor.
-2. Go back to :ref:`menuconfig <get-started-configure>`.
-3. Go to Component config --> ESP32-specific --> Main XTAL frequency, then change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz.
-4. After that, :ref:`build and flash <get-started-flash>` the application again.
+    .. figure:: ../../_static/get-started-garbled-output.png
+        :align: center
+        :alt: Garbled output
+        :figclass: align-center
+    
+    If you have such a problem, do the following:
+    
+    1. Exit the monitor.
+    2. Go back to :ref:`menuconfig <get-started-configure>`.
+    3. Go to Component config --> ESP32-specific --> Main XTAL frequency, then change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz.
+    4. After that, :ref:`build and flash <get-started-flash>` the application again.
 
 .. note::
 

docs/en/get-started/windows-setup.rst

@@ -4,8 +4,10 @@ Standard Setup of Toolchain for Windows
 
 :link_to_translation:`zh_CN:[中文]`
 
-.. note::
-      Currently only 64-bit versions of Windows are supported. 32-bit Windows can use the :doc:`Legacy GNU Make Build System<../get-started-legacy/windows-setup>`.
+.. only:: esp32
+
+    .. note::
+        Currently only 64-bit versions of Windows are supported. 32-bit Windows can use the :doc:`Legacy GNU Make Build System<../get-started-legacy/windows-setup>`.
 
 Introduction
 ============

docs/requirements.txt

@@ -12,3 +12,4 @@ sphinxcontrib-nwdiag>=0.9.5, <2.0.0
 nwdiag==1.0.4
 recommonmark
 future>=0.16.0 # for ../tools/gen_esp_err_to_name.py
+sphinx_selective_exclude==1.0.1