Merge branch 'feature/doc_update' into 'master'

ReadTheDocs documentation update

https://github.com/espressif/esp-idf/pull/89

See merge request !195

docs/api/bt.rst

@@ -18,6 +18,11 @@ API Reference
 
 .. _Instructions: template.html
 
+Header Files
+^^^^^^^^^^^^
+
+  * `bt/include/bt.h <https://github.com/espressif/esp-idf/blob/master/components/bt/include/bt.h>`_
+
 Type Definitions
 ^^^^^^^^^^^^^^^^
 

docs/api/esp_wifi.rst

@@ -18,6 +18,11 @@ API Reference
 
 .. _Instructions: template.html
 
+Header Files
+^^^^^^^^^^^^
+
+  * `esp32/include/esp_wifi.h <https://github.com/espressif/esp-idf/blob/master/components/esp32/include/esp_wifi.h>`_
+
 Macros
 ------
 
@@ -28,7 +33,6 @@ Type Definitions
 ----------------
 
 .. doxygentypedef:: wifi_promiscuous_cb_t
-.. doxygentypedef:: wifi_rxcb_t
 .. doxygentypedef:: esp_vendor_ie_cb_t
 
 Functions
@@ -68,7 +72,6 @@ Functions
 .. doxygenfunction:: esp_wifi_get_config
 .. doxygenfunction:: esp_wifi_ap_get_sta_list
 .. doxygenfunction:: esp_wifi_set_storage
-.. doxygenfunction:: esp_wifi_reg_rxcb
 .. doxygenfunction:: esp_wifi_set_auto_connect
 .. doxygenfunction:: esp_wifi_get_auto_connect
 .. doxygenfunction:: esp_wifi_set_vendor_ie

docs/api/gpio.rst

@@ -18,8 +18,13 @@ API Reference
 
 .. _Instructions: template.html
 
+Header Files
+^^^^^^^^^^^^
+
+  * `driver/include/driver/driver/gpio.h <https://github.com/espressif/esp-idf/blob/master/components/driver/include/driver/gpio.h>`_
+
 Macros
-------
+^^^^^^
 
 .. doxygendefine:: GPIO_SEL_0
 .. doxygendefine:: GPIO_SEL_1

docs/api/ledc.rst

@@ -18,6 +18,11 @@ API Reference
 
 .. _Instructions: template.html
 
+Header Files
+^^^^^^^^^^^^
+
+  * `driver/include/driver/ledc.h <https://github.com/espressif/esp-idf/blob/master/components/driver/include/driver/ledc.h>`_
+
 Data Structures
 ^^^^^^^^^^^^^^^
 

docs/api/log.rst

@@ -1,8 +1,22 @@
 .. include:: ../../components/log/README.rst
 
+Application Example
+-------------------
+
+`Instructions`_
+
 API Reference
 -------------
 
+`Instructions`_
+
+.. _Instructions: template.html
+
+Header Files
+^^^^^^^^^^^^
+
+  * `log/include/esp_log.h <https://github.com/espressif/esp-idf/blob/master/components/log/include/esp_log.h>`_
+
 Macros
 ^^^^^^
 

docs/api/nvs.rst

@@ -1,68 +0,0 @@
-.. include:: ../../components/nvs_flash/README.rst
-
-API Reference
--------------
-
-Enumerations
-^^^^^^^^^^^^
-
-.. doxygenenum:: nvs_open_mode
-
-Functions
-^^^^^^^^^
-
-.. doxygenfunction:: nvs_flash_init
-.. doxygenfunction:: nvs_flash_init_custom
-
-.. doxygenfunction:: nvs_open
-
-*Note: the following nvs_set_X function are "the same" except the data type accepted*
-
-.. doxygenfunction:: nvs_set_i8
-.. doxygenfunction:: nvs_set_u8
-.. doxygenfunction:: nvs_set_i16
-.. doxygenfunction:: nvs_set_u16
-.. doxygenfunction:: nvs_set_i32
-.. doxygenfunction:: nvs_set_u32
-.. doxygenfunction:: nvs_set_i64
-.. doxygenfunction:: nvs_set_u64
-.. doxygenfunction:: nvs_set_str
-.. doxygenfunction:: nvs_set_blob
-
-*Note: the following nvs_get_X functions are "the same" except the data type returned*
-
-.. doxygenfunction:: nvs_get_i8
-.. doxygenfunction:: nvs_get_u8
-.. doxygenfunction:: nvs_get_i16
-.. doxygenfunction:: nvs_get_u16
-.. doxygenfunction:: nvs_get_i32
-.. doxygenfunction:: nvs_get_u32
-.. doxygenfunction:: nvs_get_i64
-.. doxygenfunction:: nvs_get_u64
-.. doxygenfunction:: nvs_get_str
-.. doxygenfunction:: nvs_get_blob
-
-.. doxygenfunction:: nvs_erase_key
-.. doxygenfunction:: nvs_erase_all
-.. doxygenfunction:: nvs_commit
-.. doxygenfunction:: nvs_close
-
-Error codes
-^^^^^^^^^^^
-
-.. doxygendefine:: ESP_ERR_NVS_BASE
-.. doxygendefine:: ESP_ERR_NVS_NOT_INITIALIZED
-.. doxygendefine:: ESP_ERR_NVS_NOT_FOUND
-.. doxygendefine:: ESP_ERR_NVS_TYPE_MISMATCH
-.. doxygendefine:: ESP_ERR_NVS_READ_ONLY
-.. doxygendefine:: ESP_ERR_NVS_NOT_ENOUGH_SPACE
-.. doxygendefine:: ESP_ERR_NVS_INVALID_NAME
-.. doxygendefine:: ESP_ERR_NVS_INVALID_HANDLE
-.. doxygendefine:: ESP_ERR_NVS_REMOVE_FAILED
-.. doxygendefine:: ESP_ERR_NVS_KEY_TOO_LONG
-.. doxygendefine:: ESP_ERR_NVS_PAGE_FULL
-.. doxygendefine:: ESP_ERR_NVS_INVALID_STATE
-.. doxygendefine:: ESP_ERR_NVS_INVALID_LENGTH
-
-
-

docs/api/nvs_flash.rst

@@ -8,6 +8,12 @@ Application Example
 API Reference
 -------------
 
+Header Files
+^^^^^^^^^^^^
+
+  * `nvs_flash/include/nvs_flash.h <https://github.com/espressif/esp-idf/blob/master/components/nvs_flash/include/nvs_flash.h>`_
+  * `nvs_flash/include/nvs.h <https://github.com/espressif/esp-idf/blob/master/components/nvs_flash/include/nvs.h>`_
+
 Macros
 ^^^^^^
 

docs/api/template.rst

@@ -51,10 +51,11 @@ API Reference
 
    *INSTRUCTIONS*
  
-   1. Provide list of API members divided into sections. 
+   1. Specify the names of header files used to generate this reference. Each name should be linked to the source on `espressif/esp-idf <https://github.com/espressif/esp-idf>`_ repository.
-   2. Use corresponding ``.. doxygen..`` directives, so member documentation is auto updated.
+   2. Provide list of API members divided into sections. 
+   3. Use corresponding ``.. doxygen..`` directives, so member documentation is auto updated.
 
-     * Data Structures -``.. doxygenstruct::``
+     * Data Structures -``.. doxygenstruct::`` together with ``:members:``
      * Macros - ``.. doxygendefine::``
      * Type Definitions - ``.. doxygentypedef::``
      * Enumerations - ``.. doxygenenum::``
@@ -62,30 +63,48 @@ API Reference
 
      See `Breathe documentation <https://breathe.readthedocs.io/en/latest/directives.html>`_ for additional information. 
 
-   3. Once done remove superfluous headers.
+   4. Once done remove superfluous headers.
-   4. When changes are committed and documentation is build, check how this section rendered. :doc:`Correct annotations <../documenting-code>` in respective header files, if required.
+   5. When changes are committed and documentation is build, check how this section rendered. :doc:`Correct annotations <../documenting-code>` in respective header files, if required.
+
+Header Files
+^^^^^^^^^^^^
+
+  * `path/header-file.h`
 
 Data Structures
 ^^^^^^^^^^^^^^^
 
-``.. doxygenstruct:: name_of_structure``
+::
+
+  .. doxygenstruct:: name_of_structure
+     :members:
 
 Macros
 ^^^^^^
 
-``.. doxygendefine:: name_of_macro``
+::
+
+  .. doxygendefine:: name_of_macro
 
 Type Definitions
 ^^^^^^^^^^^^^^^^
 
-``.. doxygentypedef:: name_of_type``
+::
+
+  .. doxygentypedef:: name_of_type
 
 Enumerations
 ^^^^^^^^^^^^
 
-``.. doxygenenum:: name_of_enumeration``
+::
+
+  .. doxygenenum:: name_of_enumeration
 
 Functions
 ^^^^^^^^^
 
-``.. doxygenfunction:: name_of_function``
+::
+
+  .. doxygenfunction:: name_of_function
+
+

docs/api/uart.rst

@@ -0,0 +1,98 @@
+UART
+====
+
+Overview
+--------
+
+`Instructions`_
+
+Application Example
+-------------------
+
+`Instructions`_
+
+API Reference
+-------------
+
+`Instructions`_
+
+.. _Instructions: template.html
+
+Header Files
+^^^^^^^^^^^^
+
+  * `driver/include/driver/uart.h <https://github.com/espressif/esp-idf/blob/master/components/driver/include/driver/uart.h>`_
+
+Data Structures
+^^^^^^^^^^^^^^^
+
+.. doxygenstruct:: uart_config_t
+   :members:
+
+.. doxygenstruct:: uart_intr_config_t
+   :members:
+
+.. doxygenstruct:: uart_event_t
+   :members:
+
+Macros
+^^^^^^
+
+.. doxygendefine:: UART_FIFO_LEN
+.. doxygendefine:: UART_INTR_MASK
+.. doxygendefine:: UART_LINE_INV_MASK
+.. doxygendefine:: UART_BITRATE_MAX
+.. doxygendefine:: UART_PIN_NO_CHANGE
+.. doxygendefine:: UART_INVERSE_DISABLE
+.. doxygendefine:: UART_INVERSE_RXD
+.. doxygendefine:: UART_INVERSE_CTS
+.. doxygendefine:: UART_INVERSE_TXD
+.. doxygendefine:: UART_INVERSE_RTS
+
+Enumerations
+^^^^^^^^^^^^
+
+.. doxygenenum:: uart_word_length_t
+.. doxygenenum:: uart_stop_bits_t
+.. doxygenenum:: uart_port_t
+.. doxygenenum:: uart_parity_t
+.. doxygenenum:: uart_hw_flowcontrol_t
+.. doxygenenum:: uart_event_type_t
+
+Functions
+^^^^^^^^^
+
+.. doxygenfunction:: uart_set_word_length
+.. doxygenfunction:: uart_get_word_length
+.. doxygenfunction:: uart_set_stop_bits
+.. doxygenfunction:: uart_get_stop_bits
+.. doxygenfunction:: uart_set_parity
+.. doxygenfunction:: uart_get_parity
+.. doxygenfunction:: uart_set_baudrate
+.. doxygenfunction:: uart_get_baudrate
+.. doxygenfunction:: uart_set_line_inverse
+.. doxygenfunction:: uart_set_hw_flow_ctrl
+.. doxygenfunction:: uart_get_hw_flow_ctrl
+.. doxygenfunction:: uart_clear_intr_status
+.. doxygenfunction:: uart_enable_intr_mask
+.. doxygenfunction:: uart_disable_intr_mask
+.. doxygenfunction:: uart_enable_rx_intr
+.. doxygenfunction:: uart_disable_rx_intr
+.. doxygenfunction:: uart_disable_tx_intr
+.. doxygenfunction:: uart_enable_tx_intr
+.. doxygenfunction:: uart_isr_register
+.. doxygenfunction:: uart_set_pin
+.. doxygenfunction:: uart_set_rts
+.. doxygenfunction:: uart_set_dtr
+.. doxygenfunction:: uart_param_config
+.. doxygenfunction:: uart_intr_config
+.. doxygenfunction:: uart_driver_install
+.. doxygenfunction:: uart_driver_delete
+.. doxygenfunction:: uart_wait_tx_done
+.. doxygenfunction:: uart_tx_chars
+.. doxygenfunction:: uart_write_bytes
+.. doxygenfunction:: uart_write_bytes_with_break
+.. doxygenfunction:: uart_read_bytes
+.. doxygenfunction:: uart_flush
+
+

docs/api/vfs.rst

@@ -8,6 +8,12 @@ Application Example
 API Reference
 -------------
 
+Header Files
+^^^^^^^^^^^^
+
+  * `vfs/include/esp_vfs.h <https://github.com/espressif/esp-idf/blob/master/components/vfs/include/esp_vfs.h>`_
+  * `vfs/include/esp_vfs_dev.h <https://github.com/espressif/esp-idf/blob/master/components/vfs/include/esp_vfs_dev.h>`_
+
 Macros
 ^^^^^^
 

docs/conf.py

@@ -22,9 +22,6 @@ import os
 
 # -- Run DoxyGen to prepare XML for Sphinx---------------------------------
 # ref. https://github.com/rtfd/readthedocs.org/issues/388
-#
-# added by krzychb, 24-Oct-2016
-#
 
 from subprocess import call, Popen, PIPE
 import shlex
@@ -298,8 +295,6 @@ texinfo_documents = [
 # -- Use sphinx_rtd_theme for local builds --------------------------------
 # ref. https://github.com/snide/sphinx_rtd_theme#using-this-theme-locally-then-building-on-read-the-docs
 #
-# added by krzychb, 24-Oct-2016
-#
 # on_rtd is whether we are on readthedocs.org
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 

docs/index.rst

@@ -92,9 +92,10 @@ Contents:
    Wi-Fi <api/esp_wifi>
    Bluetooth <api/bt>
 
-   GPIO <api/gpio>
+   api/gpio
-   LED Control <api/ledc>
+   api/uart
-
+   api/ledc
+ 
    Logging <api/log>
    Non-Volatile Storage <api/nvs_flash>
    Virtual Filesystem <api/vfs>
@@ -114,6 +115,7 @@ Contents:
    :maxdepth: 1
 
    contributing
+   Style Guide <style-guide>
    documenting-code
    contributor-agreement
 

docs/style-guide.rst

@@ -172,7 +172,7 @@ To re-format a file, run::
 Documenting code
 ----------------
 
-Please see the guide here: `Documenting Code <documenting-code.rst>`_.
+Please see the guide here: :doc:`documenting-code`.
 
 Structure and naming
 --------------------