docs(common): improving documentation

- update esp_modem to use esp_docs
- migrated docs from github pages to docs.espressif.com

docs/esp_modem/en/advanced_api.rst

@@ -0,0 +1,48 @@
+Advanced esp-modem use cases
+============================
+
+This chapter outlines basic extensibility of the esp-modem component.
+
+.. _dce_factory:
+
+Custom instantiation with DCE factory
+--------------------------------------
+
+It is possible to create a modem handle in many different ways:
+
+- Build a DCE on top a generic module, user defined module or build the module only (in case the application will only use AT command interface)
+- Create the DCE as a shared, unique or a vanilla pointer
+- Create a generic DCE or a templated DCE_T of a specific module (this could be one of the supported modules or a user defined module)
+
+All the functionality is provided by the DCE factory
+
+.. doxygengroup:: ESP_MODEM_DCE_FACTORY
+   :members:
+
+.. _create_custom_module:
+
+Create custom module
+--------------------
+
+Creating a custom module is necessary if the application needs to use a specific device that is not supported
+and their commands differ from any of the supported devices. In this case it is recommended to define a new class
+representing this specific device and derive from the :cpp:class:`esp_modem::GenericModule`. In order to instantiate
+the appropriate DCE of this module, application could use :ref:`the DCE factory<dce_factory>`, and build the DCE with
+the specific module, using :cpp:func:`esp_modem::dce_factory::Factory::build`.
+
+Please refer to the implementation of the existing modules.
+
+Please note that the ``modem_console`` example defines a trivial custom modem DCE which overrides one command,
+for demonstration purposes only.
+
+
+Create new communication interface
+----------------------------------
+
+In order to connect to a device using an unsupported interface (e.g. SPI or I2C), it is necessary to implement
+a custom DTE object and supply it into :ref:`the DCE factory<dce_factory>`. The DCE is typically created in two steps:
+
+- Define and create the corresponding terminal, which communicates on the custom interface. This terminal should support basic IO methods defined in :cpp:class:`esp_modem::Terminal` and derive from it.
+- Create the DTE which uses the custom Terminal
+
+Please refer to the implementation of the existing UART DTE.

docs/esp_modem/en/api_docs.rst

@@ -0,0 +1,57 @@
+.. _c_api:
+
+C API Documentation
+===================
+
+
+The C API is very simple and consist of these two basic parts:
+
+- :ref:`lifecycle_api`
+- :ref:`modem_commands`
+
+The Typical application workflow is to:
+
+- Create a DCE instance (using :cpp:func:`esp_modem_new`)
+- Call specific functions to issue AT commands (:ref:`modem_commands`)
+- Switch to the data mode (using :cpp:func:`esp_modem_set_mode`)
+- Perform desired network operations (using standard networking API, unrelated to ESP-MODEM)
+- Optionally switch back to command mode (again :cpp:func:`esp_modem_set_mode`)
+- Destroy the DCE handle (sing :cpp:func:`esp_modem_destroy`)
+
+Note the configuration structures for DTE and DCE, needed for creating the DCE instance, is documented in :ref:`api_config`
+
+.. _lifecycle_api:
+
+Lifecycle API
+-------------
+
+These functions are used to create, destroy and set modem working mode.
+
+- :cpp:func:`esp_modem_new`
+- :cpp:func:`esp_modem_destroy`
+- :cpp:func:`esp_modem_set_mode`
+
+.. doxygengroup:: ESP_MODEM_C_API
+
+
+.. _modem_commands:
+
+Modem commands
+--------------
+
+These functions are the actual commands to communicate with the modem using AT command interface.
+
+Note that the functions which implement AT commands returning textual values use plain ``char *``
+pointer as the return value. The API expects the output data to point to user allocated space of at least
+``ESP_MODEM_C_API_STR_MAX`` (64 by default) bytes, it also truncates the output data to this size.
+
+.. doxygenfile:: esp_modem_api_commands.h
+
+.. _api_config:
+
+Configuration structures
+------------------------
+
+
+.. doxygengroup:: ESP_MODEM_CONFIG
+   :members:

docs/esp_modem/en/conf.py

@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+#
+# English Language RTD & Sphinx config file
+#
+# Uses ../conf_common.py for most non-language-specific settings.
+
+# Importing conf_common adds all the non-language-specific
+# parts to this conf module
+
+try:
+    from conf_common import *  # noqa: F403,F401
+except ImportError:
+    import os
+    import sys
+    sys.path.insert(0, os.path.abspath('../'))
+    from conf_common import *  # noqa: F403,F401
+
+# General information about the project.
+project = u'ESP-Protocols'
+copyright = u'2016 - 2022, Espressif Systems (Shanghai) Co., Ltd'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+language = 'en'

docs/esp_modem/en/cxx_api_docs.rst

@@ -0,0 +1,44 @@
+C++ API Documentation
+=====================
+
+Similar to the :ref:`c_api`, the basic application workflow consist of
+
+.. toctree::
+
+- :ref:`Construction of the DCE<cpp_init>`
+- :ref:`Switching modes<cpp_mode_switch>`
+- :ref:`Sending (AT) commands<cpp_modem_commands>`
+- :ref:`Destroying the DCE<cpp_destroy>`
+
+.. _cpp_init:
+
+Create DTE and DCE
+------------------
+
+.. doxygengroup:: ESP_MODEM_INIT_DTE
+
+.. doxygengroup:: ESP_MODEM_INIT_DCE
+
+
+.. _cpp_mode_switch:
+
+Mode switching commands
+-----------------------
+
+.. doxygenclass:: esp_modem::DCE_T
+   :members:
+
+.. _cpp_modem_commands:
+
+Modem commands
+--------------
+
+.. include:: cxx_api_links.rst
+
+.. _cpp_destroy:
+
+Destroy the DCE
+---------------
+
+The DCE object is created as ``std::unique_ptr`` by default and as such doesn't have to be explicitly destroyed.
+It simply gets destroyed and cleaned-up automatically if the object goes out of the block scope.

docs/esp_modem/en/index.rst

@@ -0,0 +1,11 @@
+ESP-MODEM Programmers manual
+============================
+
+.. toctree::
+
+   Brief intro <README>
+   C interface <api_docs>
+   C++ interface <cxx_api_docs>
+   Advanced use cases <advanced_api>
+   Internal design <internal_design>
+   Internal implementation <internal_docs>

docs/esp_modem/en/internal_design.md

@@ -0,0 +1,36 @@
+# Internal design
+
+## Design decisions
+
+* Use C++ with additional C API
+
+* Use exceptions
+  - Use macro wrapper over `try-catch` blocks when exceptions off (use `abort()` if `THROW()`)
+
+* Initializes and allocates in the constructor (might throw)
+  - easier code with exceptions ON, with exceptions OFF alloc/init failures are not treated as runtime error (program aborts)
+  - break down long initialization in constructor into more private methods
+
+* Implements different devices using inheritance from `GenericModule`, which is the most general implementation of a common modem
+  - Internally uses templates with device specialization (modeled as `DCE<SpecificModule>`) which could be used as well for some special cases,
+  such as implantation of a minimal device (ModuleIf), add new AT commands (oOnly in compile time), or using the Module with DTE only (no DCE, no Netif) for sending AT commands without network
+
+## DCE collaboration model
+
+The diagram describes how the DCE class collaborates with DTE, PPP and the device abstraction
+
+![DCE_architecture](DCE_DTE_collaboration.png)
+
+## Terminal inheritance
+
+Terminal is a class which can read or write data, and can handle callbacks when data are available. UART specialization
+is provided implementing these method using the uart driver.
+
+## CMUX terminal
+
+The below diagram depicts the idea of using CMUX terminal mode using the CMuxInstance class which is a terminal
+(it implements the basic read/write methods) interfacing arbitrary number of virtual terminals,
+but at the same time it is also composed of CMux class, which consumes the original terminal and uses its read/write methods
+to multiplex the terminal.
+
+![CMUX Terminal](CMux_collaboration.png)

docs/esp_modem/en/internal_docs.rst

@@ -0,0 +1,117 @@
+DCE Internal implementation
+===========================
+
+This chapter provides a detailed description of the classes and building blocks of the esp-modem component and their responsibilities.
+
+The esp-modem actually implements the DCE class, which in turn aggregates these thee units:
+
+- :ref:`DTE<dte_impl>` to communicate with the device on a specific Terminal interface such as UART.
+- :ref:`Netif<netif_impl>` to provide the network connectivity
+- :ref:`Module<module_impl>` to define the specific command library
+
+Developers would typically have to
+
+* Add support for a new module
+* Implement a generic (common for all modules) AT command
+
+This is explained in the :ref:`Module<module_impl>` section, as :ref:`Adding new module or command<module_addition>`
+
+------------
+
+.. doxygengroup:: ESP_MODEM_DCE
+   :members:
+
+.. _dte_impl:
+
+DTE abstraction
+---------------
+
+DTE is a basic unit to talk to the module using a Terminal interface. It also implements and uses the CMUX to multiplex
+terminals. Besides the DTE documentation, this section also refers to the
+
+- :ref:`Terminal interface<term_impl>`
+- :ref:`CMUX implementation<cmux_impl>`
+
+
+------------
+
+.. doxygengroup:: ESP_MODEM_DTE
+   :members:
+
+.. _term_impl:
+
+Terminal interface
+^^^^^^^^^^^^^^^^^^
+
+.. doxygengroup:: ESP_MODEM_TERMINAL
+   :members:
+
+.. _cmux_impl:
+
+CMUX implementation
+^^^^^^^^^^^^^^^^^^^
+
+.. doxygengroup:: ESP_MODEM_CMUX
+   :members:
+
+.. _netif_impl:
+
+Netif
+-----
+
+.. doxygengroup:: ESP_MODEM_NETIF
+   :members:
+
+.. _module_impl:
+
+Module abstraction
+------------------
+
+.. doxygengroup:: ESP_MODEM_MODULE
+   :members:
+
+.. _module_addition:
+
+Adding new devices
+^^^^^^^^^^^^^^^^^^
+
+To support a new module, developers would have to implement a new class derived from :cpp:class:`esp_modem::GenericModule` the same way
+as it is described in the  :ref:`Advanced user manual<create_custom_module>`. The only difference is that the new class (and factory extension)
+would be available in the esp_modem code base.
+
+Implement a new generic command
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Adding a generic command, i.e. the command that is shared for all modules and is included in the :cpp:class:`esp_modem::GenericModule`,
+has to be declared first in the ``include/generate/esp_modem_command_declare.inc`` file, which is the single source
+of supported command definitions, that is used in:
+
+* public C API
+* public CPP API
+* generated documentation
+* implementation of the command
+
+Therefore, a care must be taken, to correctly specify all parameters and types, especially:
+
+* Keep number of parameters low (<= 6, used in preprocessor's forwarding to the command library)
+* Use macros to specify parameter types (as they are used both from C and C++ with different underlying types)
+* Parameter names are used only for clarity and documentation, they get expanded to numbered arguments.
+
+Please use the following pattern: ``INT_IN(p1, baud)``, meaning that the parameter is an input integer,
+human readable argument name is ``baud``, it's the first argument, so expands to ``p1`` (second argument would be ``p2``, etc)
+
+Command library
+^^^^^^^^^^^^^^^
+
+This is a namespace holding a library of typical AT commands used by supported devices.
+Please refer to the :ref:`c_api` for the list of supported commands.
+
+.. doxygengroup:: ESP_MODEM_DCE_COMMAND
+   :members:
+
+
+Modem types
+-----------
+
+.. doxygengroup:: ESP_MODEM_TYPES
+   :members: