Merge branch 'doc/network' into 'master'

docs: Rearrange wifi & ethernet docs under "Networking", add tcpip_adapter docs

See merge request idf/esp-idf!3890

docs/en/api-reference/ethernet/index.rst

@@ -1,10 +0,0 @@
-Ethernet API
-************
-
-.. toctree::
-   :maxdepth: 1
-
-   Ethernet <esp_eth>
-
-
-Example code for this API section is provided in :example:`ethernet` directory of ESP-IDF examples.

docs/en/api-reference/index.rst

@@ -5,10 +5,8 @@ API Reference
 .. toctree::
    :maxdepth: 2
 
-   Wi-Fi <wifi/index>
-   Mesh <mesh/index>
    Bluetooth <bluetooth/index>
-   Ethernet <ethernet/index>
+   Networking <network/index>
    Peripherals <peripherals/index>
    Protocols <protocols/index>
    Provisioning <provisioning/index>

docs/en/api-reference/mesh/index.rst

@@ -1,9 +0,0 @@
-Mesh API
-*********
-
-.. toctree::
-   :maxdepth: 1
-
-   ESP Mesh <esp_mesh>
-
-Example code for this API section is provided in :example:`mesh` directory of ESP-IDF examples.

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

@@ -1,4 +1,4 @@
-ETHERNET
+Ethernet
 ========
 
 Application Example

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

@@ -0,0 +1,42 @@
+Networking APIs
+***************
+
+Wi-Fi
+=====
+
+.. toctree::
+   :maxdepth: 1
+
+   Wi-Fi <esp_wifi>
+   Smart Config <esp_smartconfig>
+   ESP-NOW <esp_now>
+   ESP Mesh <esp_mesh>
+
+Example code for the Wi-Fi API is provided in :example:`wifi` directory of ESP-IDF examples.
+
+Example code for ESP Mesh is provided in :example:`mesh` directory of ESP-IDF examples.
+
+Ethernet
+========
+
+.. toctree::
+   :maxdepth: 1
+
+   Ethernet <esp_eth>
+
+Example code for the Ethernet API is provided in :example:`ethernet` directory of ESP-IDF examples.
+
+IP Network Layer
+================
+
+.. toctree::
+   :maxdepth: 1
+
+   TCP/IP Adapter <tcpip_adapter.rst>
+
+Example code for TCP/IP socket APIs is provided in :example:`protocols/sockets` directory of ESP-IDF examples.
+
+Application Layer
+=================
+
+Documentation for application layer network protocols (above the IP network layer) is provided in :doc:`../protocols/index`.

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

@@ -0,0 +1,19 @@
+TCP/IP Adapter
+==============
+
+The purpose of TCP/IP Adapter library is twofold:
+
+- It provides an abstraction layer for the application on top of the TCP/IP stack. This will allow applications to choose between IP stacks in the future.
+- The APIs it provides are thread safe, even if the underlying TCP/IP stack APIs are not.
+
+ESP-IDF currently implements TCP/IP Adapter for the lwIP TCP/IP stack only. However, the adapter itself is TCP/IP implementation agnostic and different implementations are possible.
+
+Some TCP/IP Adapter API functions are intended to be called by application code, for example to get/set interface IP addresses, configure DHCP. Other functions are intended for internal ESP-IDF use by the network driver layer.
+
+In many cases, applications do not need to call TCP/IP Adapter APIs directly as they are called from the default network event handlers.
+
+API Reference
+-------------
+
+.. include:: /_build/inc/tcpip_adapter.inc
+

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

@@ -1,5 +1,5 @@
-Protocols API
-*************
+Application Protocols
+*********************
 
 .. toctree::
    :maxdepth: 1
@@ -14,3 +14,9 @@ Protocols API
    Modbus slave <modbus>
 
 Example code for this API section is provided in :example:`protocols` directory of ESP-IDF examples.
+
+
+IP Network Layer
+================
+
+Documentation for IP Network Layer protocols (below the Application Protocol layer) is provided in :doc:`../network/index`.

docs/en/api-reference/wifi/index.rst

@@ -1,12 +0,0 @@
-Wi-Fi API
-*********
-
-.. toctree::
-   :maxdepth: 1
-
-   Wi-Fi <esp_wifi>
-   Smart Config <esp_smartconfig>
-   ESPNOW <esp_now>
-
-
-Example code for this API section is provided in :example:`wifi` directory of ESP-IDF examples.