Merge branch 'docs/update_format_issues_for_api-guides' into 'master'

docs:update format issues for files under api-guides

Closes DOC-5935

See merge request espressif/esp-idf!25210

docs/en/api-guides/app_trace.rst

@@ -1,5 +1,6 @@
-Application Level Tracing library
+Application Level Tracing Library
 =================================
+
 :link_to_translation:`zh_CN:[中文]`
 
 Overview
@@ -56,11 +57,13 @@ There are two additional menuconfig options not mentioned above:
 
 4. *UART TX message size* (:ref:`CONFIG_APPTRACE_UART_TX_MSG_SIZE`). The maximum size of the single message to transfer.
 
+
 How to Use This Library
 -----------------------
 
 This library provides APIs for transferring arbitrary data between the host and {IDF_TARGET_NAME}. When enabled in menuconfig, the target application tracing module is initialized automatically at the system startup, so all what the user needs to do is to call corresponding APIs to send, receive or flush the data.
 
+
 .. _app_trace-application-specific-tracing:
 
 Application Specific Tracing
@@ -216,7 +219,7 @@ Start command syntax:
 
 Command usage examples:
 
-.. highlight:: none
+.. code-block:: none
 
 1. Collect 2048 bytes of tracing data to the file ``trace.log``. The file will be saved in the ``openocd-esp32`` directory.
 
@@ -257,7 +260,6 @@ Command usage examples:
 
 .. _app_trace-logging-to-host:
 
-
 Logging to Host
 ^^^^^^^^^^^^^^^
 
@@ -318,6 +320,7 @@ Optional arguments:
 ``--no-errors``, ``-n``
     Do not print errors.
 
+
 .. _app_trace-system-behaviour-analysis-with-segger-systemview:
 
 System Behavior Analysis with SEGGER SystemView
@@ -393,7 +396,7 @@ Start command syntax:
 
 Command usage examples:
 
-.. highlight:: none
+.. code-block:: none
 
 1.  Collect SystemView tracing data to files ``pro-cpu.SVDat`` and ``app-cpu.SVDat``. The files will be saved in ``openocd-esp32`` directory.
 
@@ -427,7 +430,7 @@ Good instructions on how to install, configure, and visualize data in Impulse fr
 
 .. note::
 
-    ESP-IDF uses its own mapping for SystemView FreeRTOS events IDs, so users need to replace the original file mapping ``$SYSVIEW_INSTALL_DIR/Description/SYSVIEW_FreeRTOS.txt`` with ``$IDF_PATH/tools/esp_app_trace/SYSVIEW_FreeRTOS.txt``. Also, contents of that IDF-specific file should be used when configuring SystemView serializer using the above link.
+    ESP-IDF uses its own mapping for SystemView FreeRTOS events IDs, so users need to replace the original file mapping ``$SYSVIEW_INSTALL_DIR/Description/SYSVIEW_FreeRTOS.txt`` with ``$IDF_PATH/tools/esp_app_trace/SYSVIEW_FreeRTOS.txt``. Also, contents of that ESP-IDF-specific file should be used when configuring SystemView serializer using the above link.
 
 .. only:: not CONFIG_FREERTOS_UNICORE
 
@@ -469,6 +472,7 @@ Generally, using Gcov to compile and run programs on the host will undergo these
 
 3. Gcov or Gcovr can be used to generate a code coverage based on the ``.gcno``, ``.gcda``, and source files. Gcov will generate a text-based coverage report for each source file in the form of a ``.gcov`` file, whilst Gcovr will generate a coverage report in HTML format.
 
+
 Gcov and Gcovr in ESP-IDF
 """""""""""""""""""""""""""
 
@@ -478,6 +482,7 @@ Using Gcov in ESP-IDF is complicated due to the fact that the program is running
 2. :ref:`app_trace-gcov-dumping-data`
 3. :ref:`app_trace-gcov-generate-report`
 
+
 .. _app_trace-gcov-setup-project:
 
 Setting Up a Project for Gcov
@@ -493,6 +498,7 @@ In order to obtain code coverage data in a project, one or more source files wit
 
 When a source file is compiled with the ``--coverage`` option (e.g., ``gcov_example.c``), the compiler will generate the ``gcov_example.gcno`` file in the project's build directory.
 
+
 Project Configuration
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -501,6 +507,7 @@ Before building a project with source code coverage, make sure that the followin
 - Enable the application tracing module by selecting ``Trace Memory`` for the :ref:`CONFIG_APPTRACE_DESTINATION1` option.
 - Enable Gcov to the host via the :ref:`CONFIG_APPTRACE_GCOV_ENABLE`.
 
+
 .. _app_trace-gcov-dumping-data:
 
 Dumping Code Coverage Data
@@ -519,11 +526,13 @@ ESP-IDF supports two methods of dumping code coverage data form the target to th
 * Instant Run-Time Dumpgit
 * Hard-coded Dump
 
+
 Instant Run-Time Dump
 ~~~~~~~~~~~~~~~~~~~~~
 
 An Instant Run-Time Dump is triggered by calling the ``{IDF_TARGET_NAME} gcov`` OpenOCD command (via a telnet session). Once called, OpenOCD will immediately preempt the {IDF_TARGET_NAME}'s current state and execute a built-in ESP-IDF Gcov debug stub function. The debug stub function will handle the dumping of data to the host. Upon completion, the {IDF_TARGET_NAME} will resume its current state.
 
+
 Hard-coded Dump
 ~~~~~~~~~~~~~~~
 
@@ -546,6 +555,7 @@ The following GDB script will add a breakpoint at :cpp:func:`esp_gcov_dump`, the
 .. note::
     Note that all OpenOCD commands should be invoked in GDB as: ``mon <oocd_command>``.
 
+
 .. _app_trace-gcov-generate-report:
 
 Generating Coverage Report
@@ -555,6 +565,7 @@ Once the code coverage data has been dumped, the ``.gcno``, ``.gcda`` and the so
 
 Both Gcov and Gcovr can be used to generate code coverage reports. Gcov is provided along with the Xtensa toolchain, whilst Gcovr may need to be installed separately. For details on how to use Gcov or Gcovr, refer to `Gcov documentation <https://gcc.gnu.org/onlinedocs/gcc/Gcov.html>`_ and `Gcovr documentation <https://gcovr.com/>`_.
 
+
 Adding Gcovr Build Target to Project
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/en/api-guides/bluetooth.rst

@@ -104,6 +104,7 @@ The table below shows whether the Bluetooth modules are supported in a specific
 
 The following sections briefly describe each layer and provide quick links to the related documents and application examples.
 
+
 ESP Bluetooth Controller
 ------------------------
 
@@ -112,6 +113,7 @@ At the bottom layer is ESP Bluetooth Controller, which encompasses various modul
 - :doc:`API reference <../api-reference/bluetooth/controller_vhci>`
 - :example:`Application examples <bluetooth/hci>`
 
+
 Hosts
 -----
 
@@ -123,10 +125,11 @@ There are two hosts, ESP-Bluedroid and ESP-NimBLE. The major difference between
 
   - ESP-Bluedroid supports both Classic Bluetooth and Bluetooth LE, while ESP-NimBLE only supports Bluetooth LE.
 
+
 ESP-Bluedroid
 ^^^^^^^^^^^^^
 
-ESP-Bluedroid is a modified version of the native Android Bluetooth stack, Bluedroid. It consists of two layers: the Bluetooth Upper Layer (BTU) and the Bluetooth Transport Controller layer (BTC). The BTU layer is responsible for processing bottom layer Bluetooth protocols such as L2CAP, GATT/ATT, SMP, GAP, and other profiles. The BTU layer provides an interface prefixed with "bta". The BTC layer is mainly responsible for providing a supported interface, prefixed with “esp”, to the application layer, processing GATT-based profiles and handling miscellaneous tasks. All the APIs are located in the ESP_API layer. Developers should use the Bluetooth APIs prefixed with “esp".
+ESP-Bluedroid is a modified version of the native Android Bluetooth stack, Bluedroid. It consists of two layers: the Bluetooth Upper Layer (BTU) and the Bluetooth Transport Controller layer (BTC). The BTU layer is responsible for processing bottom layer Bluetooth protocols such as L2CAP, GATT/ATT, SMP, GAP, and other profiles. The BTU layer provides an interface prefixed with "bta". The BTC layer is mainly responsible for providing a supported interface, prefixed with "esp", to the application layer, processing GATT-based profiles and handling miscellaneous tasks. All the APIs are located in the ESP_API layer. Developers should use the Bluetooth APIs prefixed with "esp".
 
 .. only:: esp32
 
@@ -147,6 +150,7 @@ ESP-Bluedroid is a modified version of the native Android Bluetooth stack, Blued
 
 - :example:`Application examples <bluetooth/bluedroid>`
 
+
 ESP-NimBLE
 ^^^^^^^^^^
 
@@ -162,11 +166,13 @@ ESP-NimBLE supports Bluetooth LE only. Classic Bluetooth is not supported.
 
 - :example:`Application examples <bluetooth/nimble>`
 
+
 Profiles
 --------
 
 Above the host stacks are the profile implementations by Espressif and some common profiles. Depending on your configuration, these profiles can run on ESP-Bluedroid or ESP-NimBLE.
 
+
 .. only:: SOC_BLE_MESH_SUPPORTED
 
   ESP-BLE-MESH
@@ -177,6 +183,7 @@ Above the host stacks are the profile implementations by Espressif and some comm
   - :doc:`ESP-BLE-MESH documentation <esp-ble-mesh/ble-mesh-index>`: feature list, get started, architecture, description of application examples, frequently asked questions, etc.
   - :example:`Application examples <bluetooth/esp_ble_mesh>`
 
+
 .. only:: SOC_BLUFI_SUPPORTED
 
   BluFi
@@ -187,6 +194,7 @@ Above the host stacks are the profile implementations by Espressif and some comm
   - :doc:`BluFi documentation <blufi>`
   - :example:`Application examples <bluetooth/blufi>`
 
+
 Applications
 ------------
 

docs/en/api-guides/blufi.rst

@@ -1,5 +1,6 @@
 BluFi
 ^^^^^
+
 :link_to_translation:`zh_CN:[中文]`
 
 Overview
@@ -32,7 +33,7 @@ The following uses Station as an example to illustrate the core parts of the pro
 
 7. When receiving this control frame, {IDF_TARGET_NAME} will be able to encrypt and decrypt the communication data using the shared key and the security configuration.
 
-8. The mobile phone sends the data frame defined in the section of :ref:`frame_formats`，with the Wi-Fi configuration information to {IDF_TARGET_NAME}, including SSID, password, etc.
+8. The mobile phone sends the data frame defined in the section of :ref:`frame_formats`,with the Wi-Fi configuration information to {IDF_TARGET_NAME}, including SSID, password, etc.
 
 9. The mobile phone sends a control frame of Wi-Fi connection request to {IDF_TARGET_NAME}. When receiving this control frame, {IDF_TARGET_NAME} will regard the communication of essential information as done and get ready to connect to the Wi-Fi.
 
@@ -155,7 +156,7 @@ The format of ACK Frame:
 
    * The data frame supports to be encrypted and verified.
 
-1.1 Control Frame (Binary: 0x0 b’00)
+1.1 Control Frame (Binary: 0x0 b'00)
 
 .. list-table::   
    :header-rows: 1    
@@ -233,7 +234,7 @@ The format of ACK Frame:
 
 
 
-1.2 Data Frame (Binary: 0x1 b’01)
+1.2 Data Frame (Binary: 0x1 b'01)
 
 .. list-table::      
    :header-rows: 1      
@@ -488,6 +489,6 @@ UUID
 
 BluFi Service UUID: 0xFFFF, 16 bit
 
-BluFi (the mobile -> {IDF_TARGET_NAME}): 0xFF01, writable
+BluFi (the mobile > {IDF_TARGET_NAME}): 0xFF01, writable
 
-Blufi ({IDF_TARGET_NAME} -> the mobile phone): 0xFF02, readable and callable
+Blufi ({IDF_TARGET_NAME} > the mobile phone): 0xFF02, readable and callable

docs/en/api-guides/bootloader.rst

@@ -61,7 +61,7 @@ The :ref:`first-stage-bootloader` in ROM reads the :ref:`second-stage-bootloader
 Log Level
 ---------
 
-The default bootloader log level is "Info". By setting the :ref:`CONFIG_BOOTLOADER_LOG_LEVEL` option, it's possible to increase or decrease this level. This log level is separate from the log level used in the app (see :doc:`/api-reference/system/log`).
+The default bootloader log level is "Info". By setting the :ref:`CONFIG_BOOTLOADER_LOG_LEVEL` option, it is possible to increase or decrease this level. This log level is separate from the log level used in the app (see :doc:`/api-reference/system/log`).
 
 Reducing bootloader log verbosity can improve the overall project boot time by a small amount.
 
@@ -110,7 +110,7 @@ In addition, the following configuration options control the reset condition:
 Boot from Test Firmware
 ------------------------
 
-It's possible to write a special firmware app for testing in production, and boot this firmware when needed. The project partition table will need a dedicated app partition entry for this testing app, type ``app`` and subtype ``test`` (see :doc:`/api-guides/partition-tables`).
+It is possible to write a special firmware app for testing in production, and boot this firmware when needed. The project partition table will need a dedicated app partition entry for this testing app, type ``app`` and subtype ``test`` (see :doc:`/api-guides/partition-tables`).
 
 Implementing a dedicated test app firmware requires creating a totally separate ESP-IDF project for the test app (each project in ESP-IDF only builds one app). The test app can be developed and tested independently of the main project, and then integrated at production testing time as a pre-compiled .bin file which is flashed to the address of the main project's test app partition.