API template

- reflected template in other DRAFT API dcouments
- DRAFT of Bluetooth API
- link fixes in CONTRIBUTING.rst

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index ed1c0b92d85e96f63c119aeb2eb92ee021410738..3bf43f6dbe879e9ce6fed88ab823ddccaff7e9cd 100644 (file)
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -19,7 +19,7 @@ Before sending us a Pull Request, please consider this list of points:
 
 * Is the code adequately commented for people to understand how it is structured?
 
-* Is there documentation or examples that go with code contributions? [There are additional suggestions for writing good examples in the examples README](examples/README.md).
+* Is there documentation or examples that go with code contributions? `There are additional suggestions for writing good examples in the examples README <https://github.com/espressif/esp-idf/tree/master/examples>`_.
 
 * Are comments and documentation written in clear English, with no spelling or grammar errors?
 
@@ -39,4 +39,6 @@ If this process passes, it will be merged onto the public github repository.
 Legal Part
 ----------
 
-Before a contribution can be accepted, you will need to sign our :doc:`Contributor Agreement <docs/contributor-agreement>`. You will be prompted for this automatically as part of the Pull Request process.
+Before a contribution can be accepted, you will need to sign our `Contributor Agreement <http://esp-idf.readthedocs.io/en/latest/contributing.html>`_. You will be prompted for this automatically as part of the Pull Request process.
+
+

diff --git a/docs/Doxyfile b/docs/Doxyfile
index 8328d44ca31efb16f25561934fcc489c5b0e0955..f905de74ce0955137c0f97345681937622fbce19 100644 (file)
--- a/docs/Doxyfile
+++ b/docs/Doxyfile
@@ -1,13 +1,13 @@
-PROJECT_NAME           = "ESP32 Programming Guide"
-XML_OUTPUT                     = xml
-GENERATE_LATEX         = NO
-GENERATE_MAN           = NO
-GENERATE_RTF           = NO
-CASE_SENSE_NAMES       = NO
-INPUT                          = ../components/esp32/include/esp_wifi.h ../components/driver/include/driver/gpio.h ../components/esp32/include/rom/gpio.h
-RECURSIVE                      = YES
-QUIET                          = YES
-JAVADOC_AUTOBRIEF      = YES
-GENERATE_HTML          = NO
-GENERATE_XML           = YES
-WARN_LOGFILE           = "DoxyGenWarningLog.txt"
\ No newline at end of file
+PROJECT_NAME = "ESP32 Programming Guide"
+XML_OUTPUT = xml
+GENERATE_LATEX = NO
+GENERATE_MAN = NO
+GENERATE_RTF = NO
+CASE_SENSE_NAMES = NO
+INPUT = ../components/esp32/include/esp_wifi.h ../components/driver/include/driver/gpio.h ../components/esp32/include/rom/gpio.h ../components/bt/include/bt.h
+RECURSIVE = YES
+QUIET = YES
+JAVADOC_AUTOBRIEF = YES
+GENERATE_HTML = NO
+GENERATE_XML = YES
+WARN_LOGFILE = "DoxyGenWarningLog.txt"

diff --git a/docs/api/bt.rst b/docs/api/bt.rst
new file mode 100644 (file)
index 0000000..16f30dc
--- /dev/null
+++ b/docs/api/bt.rst
@@ -0,0 +1,31 @@
+Bluetooth API
+=============
+
+Overview
+--------
+
+`Instructions <http://esp-idf.readthedocs.io/en/latest/api/template.html>`_
+
+Application Example
+-------------------
+
+`Instructions <http://esp-idf.readthedocs.io/en/latest/api/template.html>`_
+
+Reference
+---------
+
+`Instructions <http://esp-idf.readthedocs.io/en/latest/api/template.html>`_
+
+Type Definitions
+^^^^^^^^^^^^^^^^
+
+.. doxygentypedef:: vhci_host_callback
+
+Functions
+^^^^^^^^^
+
+.. doxygenfunction:: API_vhci_host_check_send_available
+.. doxygenfunction:: API_vhci_host_register_callback
+.. doxygenfunction:: API_vhci_host_send_packet
+.. doxygenfunction:: bt_controller_init
+

diff --git a/docs/api/esp_wifi.rst b/docs/api/esp_wifi.rst
index 48b4db204a065e0881cea1661536fe73269170c2..e4ec59fc82ad003a70b959c188f3817edca22a98 100644 (file)
--- a/docs/api/esp_wifi.rst
+++ b/docs/api/esp_wifi.rst
@@ -1,6 +1,21 @@
 Wi-Fi API
 =========
 
+Overview
+--------
+
+`Instructions <http://esp-idf.readthedocs.io/en/latest/api/template.html>`_
+
+Application Example
+-------------------
+
+`Instructions <http://esp-idf.readthedocs.io/en/latest/api/template.html>`_
+
+Reference
+---------
+
+`Instructions <http://esp-idf.readthedocs.io/en/latest/api/template.html>`_
+
 Macros
 ------
 

diff --git a/docs/api/example.rst b/docs/api/example.rst
deleted file mode 100644 (file)
index 88ecb46..0000000
--- a/docs/api/example.rst
+++ /dev/null
@@ -1,41 +0,0 @@
-Example Visualizations
-======================
-
-Function prototpe
------------------
-
-.. c:function:: esp_err_t esp_wifi_get_ap_list (uint16_t *number, wifi_ap_list_t *ap_list)
-.. c:function:: esp_err_t esp_wifi_set_protocol (wifi_interface_t ifx, uint8_t protocol_bitmap)
-
-
-Function definition
--------------------
-
-Wi-Fi
-^^^^^
-.. doxygenfunction:: esp_wifi_init
-.. doxygenfunction:: esp_wifi_set_config
-
-GPIO
-^^^^
-.. doxygenfunction:: gpio_isr_register
-
-Led Control
-^^^^^^^^^^^
-
-.. doxygenfunction:: ledc_timer_set    
-
-
-Enum definition
----------------
-
-.. doxygenenum:: wifi_auth_mode_t
-
-
-Struct definition
------------------
-
-.. doxygenstruct:: wifi_scan_config_t
-   :members:
-
-

diff --git a/docs/api/gpio.rst b/docs/api/gpio.rst
index 11b0e4a463975dd05fe7fd1804cd2db36801f62e..c12c991ce404a16e39072eeeb4548c94c356ec63 100644 (file)
--- a/docs/api/gpio.rst
+++ b/docs/api/gpio.rst
@@ -1,9 +1,24 @@
 GPIO API
 ========
 
-Functions
+Overview
+--------
+
+`Instructions <http://esp-idf.readthedocs.io/en/latest/api/template.html>`_
+
+Application Example
+-------------------
+
+`Instructions <http://esp-idf.readthedocs.io/en/latest/api/template.html>`_
+
+Reference
 ---------
 
+`Instructions <http://esp-idf.readthedocs.io/en/latest/api/template.html>`_
+
+Functions
+^^^^^^^^^
+
 .. doxygenfunction:: gpio_config
 .. doxygenfunction:: gpio_set_intr_type
 .. doxygenfunction:: gpio_intr_enable
@@ -16,9 +31,7 @@ Functions
 .. doxygenfunction:: gpio_wakeup_disable
 .. doxygenfunction:: gpio_isr_register
 
-*Example code:*
-
-Configuration of GPIO as an output
+*Example code:* Configuration of GPIO as an output
 
 .. code-block:: c
 
@@ -30,7 +43,7 @@ Configuration of GPIO as an output
     io_conf.pull_up_en = 0;                            //disable pull-up mode
     gpio_config(&io_conf);                             //configure GPIO with the given settings
 
-Configuration of GPIO as an input
+*Example code:* Configuration of GPIO as an input
 
 .. code-block:: c
 
@@ -43,7 +56,8 @@ Configuration of GPIO as an input
     gpio_config(&io_conf);                             //configure GPIO with the given settings
 
 
-Low level ROM GPIO functions
+ROM GPIO functions
+^^^^^^^^^^^^^^^^^^
 
 .. doxygenfunction:: gpio_init
 .. doxygenfunction:: gpio_output_set
@@ -65,3 +79,5 @@ Low level ROM GPIO functions
 .. doxygenfunction:: gpio_pad_pulldown
 .. doxygenfunction:: gpio_pad_unhold
 .. doxygenfunction:: gpio_pad_hold
+
+

diff --git a/docs/api/template.rst b/docs/api/template.rst
new file mode 100644 (file)
index 0000000..8b1dfd4
--- /dev/null
+++ b/docs/api/template.rst
@@ -0,0 +1,61 @@
+Template API
+=============
+
+Overview
+--------
+
+INSTRUCTIONS: Provide overview where and how this API may be used. For large number of functions, break down description into groups.
+
+
+Application Example
+-------------------
+
+INSTRUCTIONS: Provide one or more pratical examples to demonstrate functionality of this API.
+
+
+Reference
+---------
+
+INSTRUCTIONS: Provide list of API memebers divided into sections. Use coresponding **.. doxygen** directices, so member documentation is auto updated.
+
+* Data Structures **.. doxygenstruct**
+* Macros **.. doxygendefine**
+* Type Definitions **.. doxygentypedef**
+* Enumerations **.. doxygenenum**
+* Functions **.. doxygenfunction**
+* Variables **.. doxygenvariable**
+
+Include code snippotes to ilustrate functionality of particular functions where applicable. Skip section hearder if empty.
+
+
+Data Structures
+^^^^^^^^^^^^^^^
+
+.. Data Structures .. doxygenstruct
+
+Macros
+^^^^^^
+
+.. Macros .. doxygendefine
+
+Type Definitions
+^^^^^^^^^^^^^^^^
+
+.. Type Definitions .. doxygentypedef
+
+Enumerations
+^^^^^^^^^^^^
+
+.. Enumerations .. doxygenenum
+
+Functions
+^^^^^^^^^
+
+.. Functions .. doxygenfunction
+
+Variables
+^^^^^^^^^
+
+.. Variables .. doxygenvariable
+
+

diff --git a/docs/index.rst b/docs/index.rst
index 84f37b5600cf5e9dc8d0ae5d2764a719e2db6807..5c4d7025c652891a7c36ed1328e086fee54a314d 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,5 +1,3 @@
-.. Read the Docs Template documentation master file
-
 ESP32 Programming Guide
 =======================
 
@@ -25,7 +23,7 @@ Contents:
    Eclipse IDE <eclipse-setup>
 
 .. toctree::
-   :caption: Want More?
+   :caption: What Else?
    :maxdepth: 1
    
    partition-tables
@@ -37,8 +35,9 @@ Contents:
    :maxdepth: 1
 
    Wi-Fi <api/esp_wifi>
+   Bluetooth <api/bt>
    GPIO <api/gpio>
-   api/example
+   Template <api/template>
 
 .. toctree::
    :caption: Technical Reference