Merge branch 'feature/sphinx' into develop

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/api-reference/apps/cayenne_api.rst

@@ -0,0 +1,6 @@
+.. _api_app_cayenne_api:
+
+Cayenne MQTT API
+================
+
+.. doxygengroup:: ESP_APP_CAYENNE_API

docs/api-reference/apps/http_server.rst

@@ -0,0 +1,7 @@
+.. _api_app_http_server:
+
+HTTP Server
+===========
+
+.. doxygengroup:: ESP_APP_HTTP_SERVER
+.. doxygengroup:: ESP_APP_HTTP_SERVER_FS_FAT

docs/api-reference/apps/index.rst

@@ -0,0 +1,10 @@
+.. _api_apps:
+
+Applications
+============
+
+.. toctree::
+	:maxdepth: 2
+	:glob:
+
+	*

docs/api-reference/apps/mqtt_client.rst

@@ -0,0 +1,7 @@
+.. _api_app_mqtt_client:
+
+MQTT Client
+===========
+
+.. doxygengroup:: ESP_APP_MQTT_CLIENT
+.. doxygengroup:: ESP_APP_MQTT_CLIENT_EVT

docs/api-reference/apps/mqtt_client_api.rst

@@ -0,0 +1,6 @@
+.. _api_app_mqtt_client_api:
+
+MQTT Client API
+===============
+
+.. doxygengroup:: ESP_APP_MQTT_CLIENT_API

docs/api-reference/apps/netconn.rst

@@ -0,0 +1,6 @@
+.. _api_app_netconn:
+
+Netconn API
+===========
+
+.. doxygengroup:: ESP_NETCONN

docs/api-reference/cli/cli_config.rst

@@ -0,0 +1,6 @@
+.. _api_cli_config:
+
+CLI Configuration
+=================
+
+.. doxygengroup:: CLI_CONFIG

docs/api-reference/cli/cli_input.rst

@@ -0,0 +1,7 @@
+.. _api_cli_input:
+
+CLI Input module
+================
+
+.. doxygengroup:: CLI_INPUT
+

docs/api-reference/cli/index.rst

@@ -0,0 +1,12 @@
+.. _api_cli:
+
+Command line interface
+======================
+
+.. toctree::
+	:maxdepth: 2
+	:glob:
+
+	*
+
+.. doxygengroup:: CLI

docs/api-reference/config.rst

@@ -0,0 +1,14 @@
+.. _api_esp_config:
+
+ESP Configuration
+=================
+
+.. doxygengroup:: ESP_CONFIG
+.. doxygengroup:: ESP_CONFIG_DBG
+.. doxygengroup:: ESP_CONFIG_OS
+.. doxygengroup:: ESP_CONFIG_STD_LIB
+.. doxygengroup:: ESP_CONFIG_MODULES
+.. doxygengroup:: ESP_CONFIG_MODULES_NETCONN
+.. doxygengroup:: ESP_CONFIG_MODULES_MQTT
+.. doxygengroup:: ESP_CONFIG_MODULES_CAYENNE
+.. doxygengroup:: ESP_CONFIG_APP_HTTP

docs/api-reference/esp/ap.rst

@@ -0,0 +1,6 @@
+.. _api_esp_ap:
+
+Access point
+============
+
+.. doxygengroup:: ESP_AP

docs/api-reference/esp/buff.rst

@@ -0,0 +1,6 @@
+.. _api_esp_buff:
+
+Ring buffer
+===========
+
+.. doxygengroup:: ESP_BUFF

docs/api-reference/esp/conn.rst

@@ -0,0 +1,6 @@
+.. _api_esp_conn:
+
+Connections
+===========
+
+.. doxygengroup:: ESP_CONN

docs/api-reference/esp/debug.rst

@@ -0,0 +1,6 @@
+.. _api_esp_debug:
+
+Debug support
+=============
+
+.. doxygengroup:: ESP_DEBUG

docs/api-reference/esp/dhcp.rst

@@ -0,0 +1,6 @@
+.. _api_esp_dhcp:
+
+Dynamic Host Configuration Protocol
+===================================
+
+.. doxygengroup:: ESP_DHCP

docs/api-reference/esp/dns.rst

@@ -0,0 +1,6 @@
+.. _api_esp_dns:
+
+Domain Name System
+==================
+
+.. doxygengroup:: ESP_DNS

docs/api-reference/esp/evt.rst

@@ -0,0 +1,6 @@
+.. _api_esp_evt:
+
+Event management
+================
+
+.. doxygengroup:: ESP_EVT

docs/api-reference/esp/hostname.rst

@@ -0,0 +1,6 @@
+.. _api_esp_hostname:
+
+Hostname
+========
+
+.. doxygengroup:: ESP_HOSTNAME

docs/api-reference/esp/index.rst

@@ -0,0 +1,12 @@
+.. _api_esp:
+
+ESP AT Lib
+==========
+
+.. toctree::
+	:maxdepth: 2
+	:glob:
+
+	*
+
+.. doxygengroup:: ESP

docs/api-reference/esp/input.rst

@@ -0,0 +1,6 @@
+.. _api_esp_input:
+
+Input module
+============
+
+.. doxygengroup:: ESP_INPUT

docs/api-reference/esp/mdns.rst

@@ -0,0 +1,6 @@
+.. _api_esp_:
+
+Multicast DNS
+=============
+
+.. doxygengroup:: ESP_MDNS

docs/api-reference/esp/mem.rst

@@ -0,0 +1,6 @@
+.. _api_esp_mem:
+
+Memory manager
+==============
+
+.. doxygengroup:: ESP_MEM

docs/api-reference/esp/pbuf.rst

@@ -0,0 +1,150 @@
+.. _api_esp_pbuf:
+
+Packet buffer
+=============
+
+Packet buffer (or *pbuf*) is buffer manager to handle received data from any connection.
+It is optimized to construct big buffer of smaller chunks of fragmented data as received bytes are not always coming as single packet.
+
+Pbuf block diagram
+^^^^^^^^^^^^^^^^^^
+
+.. figure:: ../../static/images/pbuf_block_diagram.svg
+	:align: center
+	:alt: Block diagram of pbuf chain
+
+	Block diagram of pbuf chain
+
+Image above shows structure of *pbuf* chain. Each *pbuf* consists of:
+
+* Pointer to next *pbuf*, or ``NULL`` when it is last in chain
+* Length of current packet length
+* Length of current packet and all next in chain
+
+  * If *pbuf* is last in chain, total length is the same as current packet length
+
+* Reference counter, indicating how many pointers point to current *pbuf*
+* Actual buffer data
+
+Top image display ``3`` pbufs connected to single chain.
+There are ``2`` custom pointer variables to point at different *pbuf* structures. Second *pbuf* has reference counter set to ``2``, as ``2`` variables point to it:
+
+* *next* of *pbuf 1* is the first one
+* *User variable 2* is the second one
+
+.. table:: Block structure
+
+	+--------------+-----------+------------+---------------------+-------------------+
+	| Block number | Next pbuf | Block size | Total size in chain | Reference counter |
+	+==============+===========+============+=====================+===================+
+	| Block 1      | *Block 2* | ``150``    | ``550``             | ``1``             |
+	+--------------+-----------+------------+---------------------+-------------------+
+	| Block 2      | *Block 3* | ``130``    | ``400``             | ``2``             |
+	+--------------+-----------+------------+---------------------+-------------------+
+	| Block 3      | ``NULL``  | ``270``    | ``270``             | ``1``             |
+	+--------------+-----------+------------+---------------------+-------------------+
+
+Reference counter
+^^^^^^^^^^^^^^^^^
+
+Reference counter holds number of references (or variables) pointing to one block.
+It is used to properly handle memory free operation, especially when *pbuf* is used by lib core and application layer.
+
+.. note::
+	If there would be no reference counter information and application would free memory while another part of library still uses its reference, application would invoke *undefined behavior* and system could crash instantly.
+
+When application tries to free pbuf chain as on first image, it would normally call ``esp_pbuf_free`` function. That would:
+
+* Decrease reference counter by ``1``
+* If reference counter ``== 0``, free packet buffer
+* Go to next pbuf in current chain and start at first point
+
+As per first example, result of freeing would look similar to image and table below.
+
+.. figure:: ../../static/images/pbuf_block_diagram_after_free.svg
+	:align: center
+	:alt: Block diagram of pbuf chain after free from *user variable 1*
+
+	Block diagram of pbuf chain after free from *user variable 1*
+
+.. table:: Block diagram of pbuf chain after free from *user variable 1*
+
+	+--------------+-----------+------------+---------------------+-------------------+
+	| Block number | Next pbuf | Block size | Total size in chain | Reference counter |
+	+==============+===========+============+=====================+===================+
+	| Block 2      | *Block 3* | ``130``    | ``400``             | ``1``             |
+	+--------------+-----------+------------+---------------------+-------------------+
+	| Block 3      | ``NULL``  | ``270``    | ``270``             | ``1``             |
+	+--------------+-----------+------------+---------------------+-------------------+
+
+.. note::
+	*Block 1* has been successfully freed, but since *block 2* had reference counter set to ``2`` before, it was only decreased by ``1`` to a new value ``1`` and free operation stopped instead.
+	*User variable 2* is still using *pbuf* starting at *block 2* and must manually call ``esp_pbuf_free`` to free it.
+
+Concatenating vs chaining
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This section will explain difference between *concat* and *chain* operations. Both operations link ``2`` pbufs together in a chain of pbufs, difference is that *chain* operation increases *reference counter* to linked pbuf, while *concat* keeps *reference counter* at its current status.
+
+.. figure:: ../../static/images/pbuf_cat_vs_chain_1.svg
+	:align: center
+	:alt: Separate pbufs, each pointed to by separate pointers
+
+	Separate pbufs, each pointed to by separate pointers
+
+Concat operation
+****************
+
+Concat operation shall be used when ``2`` pbufs are linked together and reference to *second* is no longer used.
+
+.. figure:: ../../static/images/pbuf_cat_vs_chain_2.svg
+	:align: center
+	:alt: Structure after pbuf concat
+
+	Structure after pbuf concat
+
+After concating *2 pbufs* together, reference counter of second is still set to ``1``, however we can see that ``2`` pointers point to *second pbuf*.
+
+.. note::
+	After application calls ``esp_pbuf_cat``, it must not use pointer which points to *second pbuf*.
+	This would invoke *undefined behavior* if one pointer tries to free memory while second still points to it.
+
+An example code showing proper usage of concat operation:
+
+.. literalinclude:: ../../examples_src/pbuf_cat.c
+	:language: c
+
+Chain operation
+***************
+
+Chain operation shall be used when ``2`` pbufs are linked together and reference to *second* is still required.
+
+.. figure:: ../../static/images/pbuf_cat_vs_chain_3.svg
+	:align: center
+	:alt: Structure after pbuf chain
+
+	Structure after pbuf chain
+
+After chainin *2 pbufs* together, reference counter of second is increased by ``1``, which allows application to reference second *pbuf* separatelly.
+
+.. note::
+	After application calls ``esp_pbuf_chain``, it also has to manually free its reference using ``esp_pbuf_free`` function.
+	Forgetting to free pbuf invokes memory leak
+
+An example code showing proper usage of chain operation:
+
+.. literalinclude:: ../../examples_src/pbuf_chain.c
+	:language: c
+
+Extract pbuf data
+*****************
+
+Each *pbuf* holds some amount of data bytes. When multiple *pbufs* are linked together (either chained or concated), blocks of raw data are not linked to contiguous memory block.
+It is necessary to process block by block manually. 
+
+An example code showing proper reading of any *pbuf*:
+
+.. literalinclude:: ../../examples_src/pbuf_extract.c
+	:language: c
+
+.. doxygengroup:: ESP_PBUF

docs/api-reference/esp/ping.rst

@@ -0,0 +1,6 @@
+.. _api_esp_ping:
+
+Ping support
+============
+
+.. doxygengroup:: ESP_PING

docs/api-reference/esp/sntp.rst

@@ -0,0 +1,6 @@
+.. _api_esp_sntp:
+
+Simple Network Time Protocol
+============================
+
+.. doxygengroup:: ESP_SNTP

docs/api-reference/esp/sta.rst

@@ -0,0 +1,6 @@
+.. _api_esp_sta:
+
+Station
+=======
+
+.. doxygengroup:: ESP_STA