Merge branch 'docs/update_api-reference/protocols_and_migration-guides' into 'master'

docs: update format issues for EN and CN under api-reference/protocols and migration-guides

Closes DOC-5893

See merge request espressif/esp-idf!25090

Author: caixinying-git

docs/en/404.rst

@@ -2,17 +2,18 @@
 
 Page not Found
 ==============
+
 :link_to_translation:`zh_CN:[中文]`
 
 .. note::
 
-    We're sorry. The page you requested could not be found. This error occurs maybe because the current chip or version you choose does not support the feature you are looking for. If you want to provide feedback about this document, please let us know what exact document you want to access, so that we can better help you.
+    We are sorry. The page you requested could not be found. This error occurs maybe because the current chip or version you choose does not support the feature you are looking for. If you want to provide feedback about this document, please let us know what exact document you want to access, so that we can better help you.
 
 Please use the menu on the left to navigate through documentation contents. Optionally type the phrase you are looking for in the search box above the menu and press enter. 
 
 .. figure:: ../_static/404-page__en.svg
     :align: center
-    :alt: We're sorry. The page you requested could not be found.
+    :alt: We are sorry. The page you requested could not be found.
     :figclass: align-center
 
 * :ref:`genindex`

docs/en/about.rst

@@ -1,5 +1,6 @@
 About
 =====
+
 :link_to_translation:`zh_CN:[中文]`
 
 .. only:: esp32

docs/en/api-reference/protocols/asio.rst

@@ -1,13 +1,13 @@
-ASIO port
+ASIO Port
 =========
 
 Asio is a cross-platform C++ library, see https://think-async.com/Asio/. It provides a consistent asynchronous model using a modern C++ approach.
 
-The ESP-IDF component `ASIO` has been moved from ESP-IDF since version v5.0 to a separate repository:
+The ESP-IDF component ``ASIO`` has been moved from ESP-IDF since version v5.0 to a separate repository:
 
 * `ASIO component on GitHub <https://github.com/espressif/esp-protocols/tree/master/components/asio>`__
 
-To add ASIO component in your project, please run `idf.py add-dependency espressif/asio`
+To add ASIO component in your project, please run ``idf.py add-dependency espressif/asio``.
 
 Hosted Documentation
 --------------------

docs/en/api-reference/protocols/esp_crt_bundle.rst

@@ -6,18 +6,22 @@ Overview
 
 The ESP x509 Certificate Bundle API provides an easy way to include a bundle of custom x509 root certificates for TLS server verification.
 
-.. note:: The bundle is currently not available when using WolfSSL.
+.. note::
 
-The bundle comes with the complete list of root certificates from Mozilla’s NSS root certificate store. Using the gen_crt_bundle.py python utility the certificates’ subject name and public key are stored in a file and embedded in the {IDF_TARGET_NAME} binary.
+    The bundle is currently not available when using WolfSSL.
+
+The bundle comes with the complete list of root certificates from Mozilla's NSS root certificate store. Using the gen_crt_bundle.py python utility the certificates' subject name and public key are stored in a file and embedded in the {IDF_TARGET_NAME} binary.
 
 When generating the bundle you may choose between:
 
  * The full root certificate bundle from Mozilla, containing more than 130 certificates. The current bundle was updated Tue Jan 10 04:12:06 2023 GMT.
  * A pre-selected filter list of the name of the most commonly used root certificates, reducing the amount of certificates to around 41 while still having around 90% absolute usage coverage and 99% market share coverage according to SSL certificate authorities statistics.
 
-In addition it is possible to specify a path to a certificate file or a directory containing certificates which then will be added to the generated bundle.
+In addition, it is possible to specify a path to a certificate file or a directory containing certificates which then will be added to the generated bundle.
+
+.. note::
 
-.. note:: Trusting all root certificates means the list will have to be updated if any of the certificates are retracted. This includes removing them from `cacrt_all.pem`.
+    Trusting all root certificates means the list will have to be updated if any of the certificates are retracted. This includes removing them from ``cacrt_all.pem``.
 
 Configuration
 -------------
@@ -30,7 +34,7 @@ Most configuration is done through menuconfig. CMake will generate the bundle ac
 
 To enable the bundle when using ESP-TLS simply pass the function pointer to the bundle attach function:
 
-.. code:: c
+.. code-block:: c
 
     esp_tls_cfg_t cfg = {
          .crt_bundle_attach = esp_crt_bundle_attach,
@@ -40,7 +44,7 @@ This is done to avoid embedding the certificate bundle unless activated by the u
 
 If using mbedTLS directly then the bundle may be activated by directly calling the attach function during the setup process:
 
-.. code:: c
+.. code-block:: c
 
     mbedtls_ssl_config conf;
     mbedtls_ssl_config_init(&conf);
@@ -53,10 +57,12 @@ If using mbedTLS directly then the bundle may be activated by directly calling t
 Generating the List of Root Certificates
 ----------------------------------------
 The list of root certificates comes from Mozilla's NSS root certificate store, which can be found `here <https://wiki.mozilla.org/CA/Included_Certificates>`_
+
 The list can be downloaded and created by running the script ``mk-ca-bundle.pl`` that is distributed as a part of `curl <https://github.com/curl/curl>`_.
 Another alternative would be to download the finished list directly from the curl website: `CA certificates extracted from Mozilla <https://curl.se/docs/caextract.html>`_
 
 The common certificates bundle were made by selecting the authorities with a market share of more than 1 % from w3tech's `SSL Survey <https://w3techs.com/technologies/overview/ssl_certificate>`_.
+
 These authorities were then used to pick the names of the certificates for the filter list, `cmn_crt_authorities.csv`, from `this list <https://ccadb-public.secure.force.com/mozilla/IncludedCACertificateReportPEMCSV>`_ provided by Mozilla.
 
 

docs/en/api-reference/protocols/esp_http_client.rst

@@ -1,14 +1,15 @@
 ESP HTTP Client
 ===============
+
 :link_to_translation:`zh_CN:[中文]`
 
 Overview
 --------
 
 ``esp_http_client`` component provides a set of APIs for making HTTP/S requests from ESP-IDF applications. The steps to use these APIs are as follows:
 
-    * :cpp:func:`esp_http_client_init`: Creates an :cpp:type:`esp_http_client_handle_t` instance, i.e., an HTTP client handle based on the given :cpp:type:`esp_http_client_config_t` configuration. This function must be the first to be called; default values will be assumed for the configuration values that are not explicitly defined by the user.
-    * :cpp:func:`esp_http_client_perform`: Performs all operations of the ``esp_http_client`` - opening the connection, exchanging data, and closing the connection (as required), while blocking the current task before its completion. All related events will be invoked through the event handler (as specified in :cpp:type:`esp_http_client_config_t`).
+    * :cpp:func:`esp_http_client_init`: Creates an :cpp:type:`esp_http_client_handle_t` instance, i.e., an HTTP client handle based on the given :cpp:type:`esp_http_client_config_t` configuration. This function must be the first to be called; default values are assumed for the configuration values that are not explicitly defined by the user.
+    * :cpp:func:`esp_http_client_perform`: Performs all operations of the ``esp_http_client`` - opening the connection, exchanging data, and closing the connection (as required), while blocking the current task before its completion. All related events are invoked through the event handler (as specified in :cpp:type:`esp_http_client_config_t`).
     * :cpp:func:`esp_http_client_cleanup`: Closes the connection (if any) and frees up all the memory allocated to the HTTP client instance. This must be the last function to be called after the completion of operations.
 
 
@@ -36,7 +37,7 @@ To allow ESP HTTP client to take full advantage of persistent connections, one s
     Use Secure Element (ATECC608) for TLS
     _____________________________________
 
-    A secure element (ATECC608) can be also used for the underlying TLS connection in the HTTP client connection. Please refer to the *ATECC608A (Secure Element) with ESP-TLS* section in the :doc:`ESP-TLS documentation </api-reference/protocols/esp_tls>` for more details. The secure element support has to be first enabled in menuconfig through :ref:`CONFIG_ESP_TLS_USE_SECURE_ELEMENT`. Then the HTTP client can be configured to use secure element as follows:
+    A secure element (ATECC608) can be also used for the underlying TLS connection in the HTTP client connection. Please refer to the **ATECC608A (Secure Element) with ESP-TLS** section in the :doc:`ESP-TLS documentation </api-reference/protocols/esp_tls>` for more details. The secure element support has to be first enabled in menuconfig through :ref:`CONFIG_ESP_TLS_USE_SECURE_ELEMENT`. Then the HTTP client can be configured to use secure element as follows:
 
     .. code-block:: c
 
@@ -51,7 +52,9 @@ HTTPS Request
 
 ESP HTTP client supports SSL connections using **mbedTLS**, with the ``url`` configuration starting with ``https`` scheme or ``transport_type`` set to ``HTTP_TRANSPORT_OVER_SSL``. HTTPS support can be configured via :ref:`CONFIG_ESP_HTTP_CLIENT_ENABLE_HTTPS` (enabled by default).
 
-.. note:: While making HTTPS requests, if server verification is needed, an additional root certificate (in PEM format) needs to be provided to the ``cert_pem`` member in the ``esp_http_client_config_t`` configuration. Users can also use the ``ESP x509 Certificate Bundle`` for server verification using the ``crt_bundle_attach`` member of the ``esp_http_client_config_t`` configuration.
+.. note::
+
+    While making HTTPS requests, if server verification is needed, an additional root certificate (in PEM format) needs to be provided to the ``cert_pem`` member in the ``esp_http_client_config_t`` configuration. Users can also use the ``ESP x509 Certificate Bundle`` for server verification using the ``crt_bundle_attach`` member of the ``esp_http_client_config_t`` configuration.
 
 Check out the example functions ``https_with_url`` and ``https_with_hostname_path`` in the application example for implementation details of the above note.
 

docs/en/api-reference/protocols/esp_http_server.rst

@@ -8,16 +8,14 @@ Overview
 
 The HTTP Server component provides an ability for running a lightweight web server on {IDF_TARGET_NAME}. Following are detailed steps to use the API exposed by HTTP Server:
 
-    * :cpp:func:`httpd_start`: Creates an instance of HTTP server, allocate memory/resources for it depending upon the specified configuration and outputs a handle to the server instance. The server has both, a listening socket (TCP) for HTTP traffic, and a control socket (UDP) for control signals, which are selected in a round robin fashion in the server task loop. The task priority and stack size are configurable during server instance creation by passing httpd_config_t structure to httpd_start(). TCP traffic is parsed as HTTP requests and, depending on the requested URI, user registered handlers are invoked which are supposed to send back HTTP response packets.
-    * :cpp:func:`httpd_stop`: This stops the server with the provided handle and frees up any associated memory/resources. This is a blocking function that first signals a halt to the server task and then waits for the task to terminate. While stopping, the task will close all open connections, remove registered URI handlers and reset all session context data to empty.
+    * :cpp:func:`httpd_start`: Creates an instance of HTTP server, allocate memory/resources for it depending upon the specified configuration and outputs a handle to the server instance. The server has both, a listening socket (TCP) for HTTP traffic, and a control socket (UDP) for control signals, which are selected in a round robin fashion in the server task loop. The task priority and stack size are configurable during server instance creation by passing ``httpd_config_t`` structure to ``httpd_start()``. TCP traffic is parsed as HTTP requests and, depending on the requested URI, user registered handlers are invoked which are supposed to send back HTTP response packets.
+    * :cpp:func:`httpd_stop`: This stops the server with the provided handle and frees up any associated memory/resources. This is a blocking function that first signals a halt to the server task and then waits for the task to terminate. While stopping, the task closes all open connections, removes registered URI handlers and resets all session context data to empty.
     * :cpp:func:`httpd_register_uri_handler`: A URI handler is registered by passing object of type ``httpd_uri_t`` structure which has members including ``uri`` name, ``method`` type (eg. ``HTTPD_GET/HTTPD_POST/HTTPD_PUT`` etc.), function pointer of type ``esp_err_t *handler (httpd_req_t *req)`` and ``user_ctx`` pointer to user context data.
 
 Application Example
 -------------------
 
-    .. highlight:: c
-
-    ::
+    .. code-block:: c
 
         /* Our URI handler function to be called during GET /uri request */
         esp_err_t get_handler(httpd_req_t *req)
@@ -119,9 +117,7 @@ HTTP server features persistent connections, allowing for the re-use of the same
 Persistent Connections Example
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. highlight:: c
-
-::
+.. code-block:: c
 
     /* Custom function to free context */
     void free_ctx_func(void *ctx)

docs/en/api-reference/protocols/esp_https_server.rst

@@ -1,5 +1,6 @@
 HTTPS Server
 ============
+
 :link_to_translation:`zh_CN:[中文]`
 
 Overview