Merge branch 'docs/update_format_issues_wrongly_added_to_the_ingore_f…

…ile' into 'master'

docs: update document format issues

Closes DOC-6383

See merge request espressif/esp-idf!26096

docs/en/api-guides/app_trace.rst

@@ -219,7 +219,7 @@ Start command syntax:
 
 Command usage examples:
 
-.. code-block:: none
+.. highlight:: none
 
 1. Collect 2048 bytes of tracing data to the file ``trace.log``. The file will be saved in the ``openocd-esp32`` directory.
 
@@ -336,7 +336,7 @@ Support for this feature is enabled by ``Component config`` > ``Application Leve
 
 1. SytemView destination. Select the destination interface: JTAG or UART. In case of UART, it will be possible to connect SystemView application to the {IDF_TARGET_NAME} directly and receive data in real-time.
 
-2. {IDF_TARGET_NAME} timer to use as SystemView timestamp source: (:ref:`CONFIG_APPTRACE_SV_TS_SOURCE`) selects the source of timestamps for SystemView events. In the single core mode, timestamps are generated using {IDF_TARGET_NAME} internal cycle counter running at maximum 240 Mhz (~4 ns granularity). In the dual-core mode, external timer working at 40 Mhz is used, so the timestamp granularity is 25 ns.
+2. {IDF_TARGET_NAME} timer to use as SystemView timestamp source: (:ref:`CONFIG_APPTRACE_SV_TS_SOURCE`) selects the source of timestamps for SystemView events. In the single core mode, timestamps are generated using {IDF_TARGET_NAME} internal cycle counter running at maximum 240 Mhz (about 4 ns granularity). In the dual-core mode, external timer working at 40 Mhz is used, so the timestamp granularity is 25 ns.
 
 3. Individually enabled or disabled collection of SystemView events (``CONFIG_APPTRACE_SV_EVT_XXX``):
 
@@ -396,7 +396,7 @@ Start command syntax:
 
 Command usage examples:
 
-.. code-block:: none
+.. highlight:: none
 
 1.  Collect SystemView tracing data to files ``pro-cpu.SVDat`` and ``app-cpu.SVDat``. The files will be saved in ``openocd-esp32`` directory.
 

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

@@ -64,7 +64,7 @@ Using CMake Directly
 
 :ref:`idf.py` is a wrapper around CMake_ for convenience. However, you can also invoke CMake directly if you prefer.
 
-.. code-block:: bash
+.. highlight:: bash
 
 When ``idf.py`` does something, it prints each command that it runs for easy reference. For example, the ``idf.py build`` command is the same as running these commands in a bash shell (or similar commands for Windows Command Prompt)::
 
@@ -147,7 +147,7 @@ To manage the Python version more generally via the command line, check out the
 Example Project
 ===============
 
-.. code-block:: none
+.. highlight:: none
 
 An example project directory tree might look like this::
 
@@ -198,7 +198,7 @@ Each project has a single top-level ``CMakeLists.txt`` file that contains build
 Minimal Example CMakeLists
 --------------------------
 
-.. code-block:: cmake
+.. highlight:: cmake
 
 Minimal project::
 
@@ -256,7 +256,7 @@ Overriding Default Build Specifications
 
 The build sets some global build specifications (compile flags, definitions, etc.) that gets used in compiling all sources from all components.
 
-.. code-block:: cmake
+.. highlight:: cmake
 
 For example, one of the default build specifications set is the compile option ``-Wextra``. Suppose a user wants to use override this with ``-Wno-extra``,
 it should be done after ``project()``::
@@ -306,7 +306,7 @@ When ESP-IDF is collecting all the components to compile, it will do this in the
 Minimal Component CMakeLists
 ----------------------------
 
-.. code-block:: cmake
+.. highlight:: cmake
 
 The minimal component ``CMakeLists.txt`` file simply registers the component to the build system using ``idf_component_register``::
 
@@ -373,7 +373,7 @@ Other build properties are listed :ref:`here <cmake-build-properties>`.
 Controlling Component Compilation
 ---------------------------------
 
-.. code-block:: cmake
+.. highlight:: cmake
 
 To pass compiler options when compiling source files belonging to a particular component, use the `target_compile_options`_ function::
 
@@ -475,7 +475,7 @@ Imagine there is a ``car`` component, which uses the ``engine`` component, which
 Car Component
 ^^^^^^^^^^^^^
 
-.. code-block:: c
+.. highlight:: c
 
 The ``car.h`` header file is the public interface for the ``car`` component. This header includes ``engine.h`` directly because it uses some declarations from this header::
 
@@ -507,7 +507,7 @@ This means the ``car/CMakeLists.txt`` file needs to declare that ``car`` require
 Engine Component
 ^^^^^^^^^^^^^^^^
 
-.. code-block:: c
+.. highlight:: c
 
 The ``engine`` component also has a public header file ``include/engine.h``, but this header is simpler::
 
@@ -664,7 +664,7 @@ The order of components in the ``BUILD_COMPONENTS`` variable determines other or
 Adding Link-Time Dependencies
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. code-block:: cmake
+.. highlight:: cmake
 
 The ESP-IDF CMake helper function ``idf_component_add_link_dependency`` adds a link-only dependency between one component and another. In almost all cases, it is better to use the ``PRIV_REQUIRES`` feature in ``idf_component_register`` to create a dependency. However, in some cases, it's necessary to add the link-time dependency of another component to this component, i.e., the reverse order to ``PRIV_REQUIRES`` (for example: :doc:`/api-reference/peripherals/spi_flash/spi_flash_override_driver`).
 
@@ -816,7 +816,7 @@ Adding Conditional Configuration
 
 The configuration system can be used to conditionally compile some files depending on the options selected in the project configuration.
 
-.. code-block:: none
+.. highlight:: none
 
 ``Kconfig``::
 
@@ -859,7 +859,7 @@ This can also be used to select or stub out an implementation, as such:
         help
             Select this to output temperature plots
 
-.. code-block:: cmake
+.. highlight:: cmake
 
 ``CMakeLists.txt``::
 
@@ -932,7 +932,7 @@ Or if the file is a string, you can use the variable ``EMBED_TXTFILES``. This wi
   idf_component_register(...
                          EMBED_TXTFILES server_root_cert.pem)
 
-.. code-block:: c
+.. highlight:: c
 
 The file's contents will be added to the .rodata section in flash, and are available via symbol names as follows::
 
@@ -941,7 +941,7 @@ The file's contents will be added to the .rodata section in flash, and are avail
 
 The names are generated from the full name of the file, as given in ``EMBED_FILES``. Characters /, ., etc. are replaced with underscores. The _binary prefix in the symbol name is added by objcopy and is the same for both text and binary files.
 
-.. code-block:: cmake
+.. highlight:: cmake
 
 To embed a file into a project, rather than a component, you can call the function ``target_add_binary_data`` like this::
 
@@ -951,7 +951,7 @@ Place this line after the ``project()`` line in your project CMakeLists.txt file
 
 For an example of using this technique, see the "main" component of the file_serving example :example_file:`protocols/http_server/file_serving/main/CMakeLists.txt` - two files are loaded at build time and linked into the firmware.
 
-.. code-block:: cmake
+.. highlight:: cmake
 
 It is also possible to embed a generated file::
 
@@ -980,7 +980,7 @@ ESP-IDF has a feature called linker script generation that enables components to
 Fully Overriding the Component Build Process
 --------------------------------------------
 
-.. code-block:: cmake
+.. highlight:: cmake
 
 Obviously, there are cases where all these recipes are insufficient for a certain component, for example when the component is basically a wrapper around another third-party component not originally intended to be compiled under this build system. In that case, it's possible to forego the ESP-IDF build system entirely by using a CMake feature called ExternalProject_. Example component CMakeLists::
 
@@ -1077,7 +1077,7 @@ After running a project build, the build directory contains binary output files
 - ``flash_app_args`` contains arguments to flash only the app.
 - ``flash_bootloader_args`` contains arguments to flash only the bootloader.
 
-.. code-block:: bash
+.. highlight:: bash
 
 You can pass any of these flasher argument files to ``esptool.py`` as follows::
 
@@ -1105,7 +1105,7 @@ The ESP-IDF build system "wraps" CMake with the concept of "components", and hel
 
 However, underneath the concept of "components" is a full CMake build system. It is also possible to make a component which is pure CMake.
 
-.. code-block:: cmake
+.. highlight:: cmake
 
 Here is an example minimal "pure CMake" component CMakeLists file for a component named ``json``::
 
@@ -1125,7 +1125,7 @@ Using Third-Party CMake Projects with Components
 
 CMake is used for a lot of open-source C and C++ projects — code that users can tap into for their applications. One of the benefits of having a CMake build system is the ability to import these third-party projects, sometimes even without modification! This allows for users to be able to get functionality that may not yet be provided by a component, or use another library for the same functionality.
 
-.. code-block:: cmake
+.. highlight:: cmake
 
 Importing a library might look like this for a hypothetical library ``foo`` to be used in the ``main`` component::
 
@@ -1167,7 +1167,7 @@ For example, in the ``foo/CMakeLists.txt`` file::
 Using Prebuilt Libraries with Components
 ========================================
 
-.. code-block:: cmake
+.. highlight:: cmake
 
 Another possibility is that you have a prebuilt static library (``.a`` file), built by some other build process.
 
@@ -1430,7 +1430,7 @@ These are properties that describe a component. Values of component properties c
 File Globbing & Incremental Builds
 ==================================
 
-.. code-block:: cmake
+.. highlight:: cmake
 
 The preferred way to include source files in an ESP-IDF component is to list them manually via SRCS argument to ``idf_component_register``::
 

docs/en/api-guides/error-handling.rst

@@ -1,4 +1,4 @@
-.. code-block:: c
+.. highlight:: c
 
 Error Handling
 ==============

docs/en/api-guides/jtag-debugging/building-openocd-linux.rst

@@ -7,7 +7,7 @@ Building OpenOCD from Sources for Linux
 The following instructions are alternative to downloading binary OpenOCD from `Espressif GitHub <https://github.com/espressif/openocd-esp32/releases>`_. To quickly setup the binary OpenOCD, instead of compiling it yourself, backup and proceed to section :ref:`jtag-debugging-setup-openocd`.
 
 
-.. code-block:: bash
+.. highlight:: bash
 
 Download Sources of OpenOCD
 ===========================

docs/en/api-guides/jtag-debugging/building-openocd-macos.rst

@@ -6,7 +6,7 @@ Building OpenOCD from Sources for MacOS
 
 The following instructions are alternative to downloading binary OpenOCD from `Espressif GitHub <https://github.com/espressif/openocd-esp32/releases>`_. To quickly setup the binary OpenOCD, instead of compiling it yourself, backup and proceed to section :ref:`jtag-debugging-setup-openocd`.
 
-.. code-block:: bash
+.. highlight:: bash
 
 Download Sources of OpenOCD
 ===========================

docs/en/api-guides/jtag-debugging/debugging-examples.rst

@@ -5,7 +5,7 @@ Debugging Examples
 
 This section describes debugging with GDB from :ref:`jtag-debugging-examples-eclipse` as well as from :ref:`jtag-debugging-examples-command-line`.
 
-.. code-block:: none
+.. highlight:: none
 
 
 .. _jtag-debugging-examples-eclipse:

docs/en/api-guides/wifi-security.rst

@@ -18,9 +18,9 @@ Protected Management Frames (PMF)
 Introduction
 ++++++++++++
 
-In Wi-Fi, management frames such as beacons, probes, (de)authentication, and (dis)association are used by non-AP stations to scan and connect to an AP. Unlike data frames, these frames are sent unencrypted.
+In Wi-Fi, management frames such as beacons, probes, authentication/deauthentication, and association/disassociation are used by non-AP stations to scan and connect to an AP. Unlike data frames, these frames are sent unencrypted.
 
-An attacker can use eavesdropping and packet injection to send spoofed (de)authentication/(dis)association frames at the right time, leading to attacks such as Denial-of-Service (DOS) and man-in-the-middle.
+An attacker can use eavesdropping and packet injection to send spoofed authentication/deauthentication or association/disassociation frames at the right time, leading to attacks such as Denial-of-Service (DOS) and man-in-the-middle.
 
 PMF provides protection against these attacks by encrypting unicast management frames and providing integrity checks for broadcast management frames. These include deauthentication, disassociation, and robust management frames. It also provides a Secure Association (SA) teardown mechanism to prevent spoofed association/authentication frames from disconnecting already connected clients.
 

docs/en/api-reference/network/esp_now.rst

@@ -22,7 +22,7 @@ ESP-NOW uses a vendor-specific action frame to transmit ESP-NOW data. The defaul
     ------------------------------------------------------------------------------------------------------------
     | MAC Header | Category Code | Organization Identifier | Random Values | Vendor Specific Content |   FCS   |
     ------------------------------------------------------------------------------------------------------------
-      24 bytes         1 byte              3 bytes               4 bytes             7~257 bytes        4 bytes 
+      24 bytes         1 byte              3 bytes               4 bytes             7-257 bytes        4 bytes
 
 - Category Code: The Category Code field is set to the value (127) indicating the vendor-specific category.
 - Organization Identifier: The Organization Identifier contains a unique identifier (0x18fe34), which is the first three bytes of MAC address applied by Espressif.
@@ -36,7 +36,7 @@ ESP-NOW uses a vendor-specific action frame to transmit ESP-NOW data. The defaul
     -------------------------------------------------------------------------------
     | Element ID | Length | Organization Identifier | Type | Version |    Body    |
     -------------------------------------------------------------------------------
-        1 byte     1 byte            3 bytes         1 byte   1 byte   0~250 bytes 
+        1 byte     1 byte            3 bytes         1 byte   1 byte   0-250 bytes
 
 - Element ID: The Element ID field is set to the value (221), indicating the vendor-specific element.
 - Length: The length is the total length of Organization Identifier, Type, Version and Body.
@@ -89,7 +89,7 @@ If there is a lot of ESP-NOW data to send, call :cpp:func:`esp_now_send()` to se
 Receiving ESP-NOW Data
 ----------------------
 
-Call :cpp:func:`esp_now_register_recv_cb()` to register receiving callback function.  Call the receiving callback function when receiving ESP-NOW. The receiving callback function also runs from the Wi-Fi task. So, do not do lengthy operations in the callback function. 
+Call :cpp:func:`esp_now_register_recv_cb()` to register receiving callback function.  Call the receiving callback function when receiving ESP-NOW. The receiving callback function also runs from the Wi-Fi task. So, do not do lengthy operations in the callback function.
 Instead, post the necessary data to a queue and handle it from a lower priority task.
 
 Config ESP-NOW Rate

docs/en/api-reference/peripherals/sdio_slave.rst

@@ -96,7 +96,7 @@ Connections
 
         Here is a list of modules/kits with 3.3 V flash:
 
-        - Modules: All modules except ESP32-WROVER、ESP32-WROVER-I、ESP32-S3-WROOM-2, and please check `模组概览 <https://www.espressif.com/zh-hans/products/modules>`__ for module list
+        - Modules: All modules except ESP32-WROVER, ESP32-WROVER-I, ESP32-S3-WROOM-2, and please check `Modules Overview <https://www.espressif.com/en/products/modules>`__ for module list
         - Kits: ESP32-PICO-KIT, ESP32-DevKitC (up to v4), ESP32-WROVER-KIT (v4.1 [also known as ESP32-WROVER-KIT-VB], v2, v1 [also known as DevKitJ v1])
 
         You can tell the version of your ESP23-WROVER-KIT version from the module on it: v4.1 are with ESP32-WROVER-B modules, v3 are with ESP32-WROVER modules, while v2 and v1 are with ESP32-WROOM-32 modules.
@@ -170,7 +170,7 @@ The host can trigger an interruption in the slave by writing a single bit to the
 
 .. note::
 
-  The callback function is called in the ISR. Do not use any delay, loop or blocking function in the callback, e.g. mutex.
+  The callback function is called in the ISR. Do not use any delay, loop or blocking function in the callback, e.g., mutex.
 
 Similar to the previous information, there's an alternative set of functions available. You can call ``sdio_slave_wait_int`` to wait for an interrupt within a certain time, or call ``sdio_slave_clear_int`` to clear interrupts from host. The callback function can work with the wait functions perfectly.
 

docs/en/api-reference/peripherals/usb_device.rst

@@ -32,7 +32,7 @@ Hardware USB Connection
 
 - Any board with the {IDF_TARGET_NAME} chip with USB connectors or with exposed USB's D+ and D- (DATA+/DATA-) pins.
 
-If the board has no USB connector but has the pins, connect pins directly to the host (e.g. with do-it-yourself cable from any USB connection cable).
+If the board has no USB connector but has the pins, connect pins directly to the host (e.g., with do-it-yourself cable from any USB connection cable).
 
 On {IDF_TARGET_NAME}, connect GPIO {IDF_TARGET_USB_DP_GPIO_NUM} and {IDF_TARGET_USB_DM_GPIO_NUM} to D+/D- respectively:
 
@@ -95,7 +95,7 @@ Install Driver
 
 To initialize the driver, users should call :cpp:func:`tinyusb_driver_install`. The driver's configuration is specified in a :cpp:type:`tinyusb_config_t` structure that is passed as an argument to :cpp:func:`tinyusb_driver_install`.
 
- Note that the :cpp:type:`tinyusb_config_t` structure can be zero initialized (e.g. ``const tinyusb_config_t tusb_cfg = { 0 };``) or partially (as shown below). For any member that is initialized to `0` or `NULL`, the driver will use its default configuration values for that member (see example below)
+ Note that the :cpp:type:`tinyusb_config_t` structure can be zero initialized (e.g., ``const tinyusb_config_t tusb_cfg = { 0 };``) or partially (as shown below). For any member that is initialized to `0` or `NULL`, the driver will use its default configuration values for that member (see example below)
 
 .. code-block:: c