alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-09-20 10:46:02 -04:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Merge branch 'feature/doc_update' into 'master'

Browse Source 
ReadTheDocs documentation update

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

See merge request !195
This commit is contained in:
Ivan Grokhotkov 2016-11-14 10:06:33 +08:00
commit 6eac435723
13 changed files with 180 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
docs/api/bt.rst
View File

@ -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
^^^^^^^^^^^^^^^^

7
docs/api/esp_wifi.rst
View File

@ -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

7
docs/api/gpio.rst
View File

@ -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

5
docs/api/ledc.rst
View File

@ -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
^^^^^^^^^^^^^^^

14
docs/api/log.rst
View File

@ -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
^^^^^^

68
docs/api/nvs.rst
View File

@ -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

6
docs/api/nvs_flash.rst
View File

@ -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
^^^^^^

39
docs/api/template.rst
View File

@ -51,10 +51,11 @@ API Reference
*INSTRUCTIONS*
1. Provide list of API members divided into sections.
2. Use corresponding ``.. doxygen..`` directives, so member documentation is auto updated.
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. 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. When changes are committed and documentation is build, check how this section rendered. :doc:`Correct annotations <../documenting-code>` in respective header files, if required.
4. Once done remove superfluous headers.
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

98
docs/api/uart.rst Normal file
View File

@ -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

6
docs/api/vfs.rst
View File

@ -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
^^^^^^

5
docs/conf.py
View File

@ -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'

8
docs/index.rst
View File

@ -92,9 +92,10 @@ Contents:
Wi-Fi <api/esp_wifi>
Bluetooth <api/bt>
GPIO <api/gpio>
LED Control <api/ledc>
api/gpio
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

2
docs/style-guide.rst
View File

@ -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
--------------------