Merge branch 'feature/api_doc' into 'master'

API reference, first batch This includes fixes to documentation formats in header files, some standalone doc fixes, necessary files for readthedocs, and instructions for documenting the code. See merge request !162
2016-11-01 22:25:20 +08:00 · 2016-11-01 22:25:20 +08:00 · d76868eec1
commit d76868eec1
parent c7f8d206ed 4f71d741ec
39 changed files with 1455 additions and 220 deletions
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@ -92,6 +92,20 @@ build_examples:
    - cd build_examples
    - ${IDF_PATH}/make/build_examples.sh

+build_docs:
+  stage: build
+  image: espressif/esp32-ci-env
+  tags:
+    - build_docs
+  script:
+    - cd docs
+    - make html
+  artifacts:
+    paths:
+      - docs/_build/html
+    expire_in: 1 mos
+
+
 test_nvs_on_host:
  stage: test
  image: espressif/esp32-ci-env
@ -159,6 +173,31 @@ push_master_to_github:
    - git push --follow-tags github HEAD:master


+deploy_docs:
+  before_script:
+    - echo "Not setting up GitLab key, not fetching submodules"
+  stage: deploy
+  only:
+   - master
+   - triggers
+  tags:
+    - deploy
+  image: espressif/esp32-ci-env
+  script:
+    - mkdir -p ~/.ssh
+    - chmod 700 ~/.ssh
+    - echo -n $DOCS_DEPLOY_KEY > ~/.ssh/id_rsa_base64
+    - base64 --decode --ignore-garbage ~/.ssh/id_rsa_base64 > ~/.ssh/id_rsa
+    - chmod 600 ~/.ssh/id_rsa
+    - echo -e "Host $DOCS_SERVER\n\tStrictHostKeyChecking no\n\tUser $DOCS_SERVER_USER\n" >> ~/.ssh/config
+    - export GIT_VER=$(git describe --always)
+    - cd docs/_build/
+    - mv html $GIT_VER
+    - tar czvf $GIT_VER.tar.gz $GIT_VER
+    - scp $GIT_VER.tar.gz $DOCS_SERVER:$DOCS_PATH
+    - ssh $DOCS_SERVER -x "cd $DOCS_PATH && tar xzvf $GIT_VER.tar.gz && rm -f latest && ln -s $GIT_VER latest"
+
+
 # AUTO GENERATED PART START, DO NOT MODIFY CONTENT BELOW
 # template for test jobs
 .test_template: &test_template
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@ -1,12 +1,15 @@
-# Contributions Guide
+Contributions Guide
+===================

 We welcome contributions to the esp-idf project!

-## How to Contribute
+How to Contribute
+-----------------

-Contributions to esp-idf - fixing bugs, adding features, adding documentation - are welcome. We accept contributions via [Github Pull Requests](https://help.github.com/articles/about-pull-requests/).
+Contributions to esp-idf - fixing bugs, adding features, adding documentation - are welcome. We accept contributions via `Github Pull Requests <https://help.github.com/articles/about-pull-requests/>`_.

-## Before Contributing
+Before Contributing
+-------------------

 Before sending us a Pull Request, please consider this list of points:

@ -16,15 +19,16 @@ 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?

-* If the contribution contains multiple commits, are they grouped together into logical changes (one major change per pull request)? Are any commits with names like "fixed typo" [squashed into previous commits](http://eli.thegreenplace.net/2014/02/19/squashing-github-pull-requests-into-a-single-commit/)?
+* If the contribution contains multiple commits, are they grouped together into logical changes (one major change per pull request)? Are any commits with names like "fixed typo" `squashed into previous commits <http://eli.thegreenplace.net/2014/02/19/squashing-github-pull-requests-into-a-single-commit/>`_?

 * If you're unsure about any of these points, please open the Pull Request anyhow and then ask us for feedback.

-## Pull Request Process
+Pull Request Process
+--------------------

 After you open the Pull Request, there will probably be some discussion in the comments field of the request itself.

@ -32,6 +36,9 @@ Once the Pull Request is ready to merge, it will first be merged into our intern

 If this process passes, it will be merged onto the public github repository.

-## Legal Part
+Legal Part
+----------
+
+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.
+

-Before a contribution can be accepted, you will need to sign our [Contributor Agreement](docs/contributor-agreement.rst). You will be prompted for this automatically as part of the Pull Request process.
--- a/README.md
+++ b/README.md
@ -1,5 +1,7 @@
 # Using Espressif IoT Development Framework with the ESP32

+[![alt text](https://readthedocs.org/projects/docs/badge/?version=latest "Documentation Status")](http://esp-idf.readthedocs.io/en/latest/?badge=latest)
+
 # Setting Up ESP-IDF

 In the [docs](docs) directory you will find per-platform setup guides:
@ -60,14 +62,15 @@ The simplest way to use the partition table is to `make menuconfig` and choose o

 In both cases the factory app is flashed at offset 0x10000. If you `make partition_table` then it will print a summary of the partition table.

-For more details about partition tables and how to create custom variations, view the `docs/partition_tables.rst` file.
+For more details about partition tables and how to create custom variations, view the `docs/partition-tables.rst` file.

 # Resources

-* The [docs directory of the esp-idf repository](docs) contains esp-idf documentation.
+* The [docs directory of the esp-idf repository](docs) contains source of [esp-idf](http://esp-idf.readthedocs.io/) documentation.

 * The [esp32.com forum](http://esp32.com/) is a place to ask questions and find community resources.

 * [Check the Issues section on github](https://github.com/espressif/esp-idf/issues) if you find a bug or have a feature request. Please check existing Issues before opening a new one.

-* If you're interested in contributing to esp-idf, please check the [CONTRIBUTING.md](CONTRIBUTING.md) file.
+* If you're interested in contributing to esp-idf, please check the [Contributions Guide](http://esp-idf.readthedocs.io/en/latest/contributing.html>).
+
--- a/components/bt/include/bt.h
+++ b/components/bt/include/bt.h
@ -28,37 +28,36 @@ extern "C" {
 *
 * This function should be called only once, before any other BT functions are called.
 */
-void bt_controller_init();
+void bt_controller_init(void);

-/** @brief: vhci_host_callback
+/** @brief vhci_host_callback
 *  used for vhci call host function to notify what host need to do
 *  
 *  notify_host_send_available: notify host can send packet to controller
 *  notify_host_recv: notify host that controller has packet send to host
 */
 typedef struct vhci_host_callback {
-
    void (*notify_host_send_available)(void);
    int (*notify_host_recv)(uint8_t *data, uint16_t len);
 } vhci_host_callback_t;

-/** @brief: API_vhci_host_check_send_available
+/** @brief API_vhci_host_check_send_available
 *  used for check actively if the host can send packet to controller or not.
- *  return true for ready to send, false means cannot send packet
+ *  @return true for ready to send, false means cannot send packet
 */
 bool API_vhci_host_check_send_available(void);

-/** @brief: API_vhci_host_send_packet
+/** @brief API_vhci_host_send_packet
 * host send packet to controller
- * param data is the packet point, the param len is the packet length
- * return void
+ * @param data the packet point
+ *,@param len the packet length
 */
 void API_vhci_host_send_packet(uint8_t *data, uint16_t len);

-/** @brief: API_vhci_host_register_callback
+/** @brief API_vhci_host_register_callback
 * register the vhci referece callback, the call back
 * struct defined by vhci_host_callback structure.
- * param is the vhci_host_callback type variable
+ * @param callback vhci_host_callback type variable
 */
 void API_vhci_host_register_callback(const vhci_host_callback_t *callback);

--- a/components/driver/include/driver/gpio.h
+++ b/components/driver/include/driver/gpio.h
@ -157,39 +157,39 @@ typedef enum {
 } gpio_num_t;

 typedef enum {
-    GPIO_INTR_DISABLE = 0,     /* disable GPIO interrupt                             */
-    GPIO_INTR_POSEDGE = 1,     /* GPIO interrupt type : rising edge                  */
-    GPIO_INTR_NEGEDGE = 2,     /* GPIO interrupt type : falling edge                 */
-    GPIO_INTR_ANYEDGE = 3,     /* GPIO interrupt type : both rising and falling edge */
-    GPIO_INTR_LOW_LEVEL = 4,   /* GPIO interrupt type : input low level trigger      */
-    GPIO_INTR_HIGH_LEVEL = 5,  /* GPIO interrupt type : input high level trigger     */
+    GPIO_INTR_DISABLE = 0,     /*!< disable GPIO interrupt                             */
+    GPIO_INTR_POSEDGE = 1,     /*!< GPIO interrupt type : rising edge                  */
+    GPIO_INTR_NEGEDGE = 2,     /*!< GPIO interrupt type : falling edge                 */
+    GPIO_INTR_ANYEDGE = 3,     /*!< GPIO interrupt type : both rising and falling edge */
+    GPIO_INTR_LOW_LEVEL = 4,   /*!< GPIO interrupt type : input low level trigger      */
+    GPIO_INTR_HIGH_LEVEL = 5,  /*!< GPIO interrupt type : input high level trigger     */
    GPIO_INTR_MAX,
 } gpio_int_type_t;

 typedef enum {
-    GPIO_MODE_INPUT = GPIO_MODE_DEF_INPUT,                                                         /* GPIO mode : input only                           */
-    GPIO_MODE_OUTPUT = GPIO_MODE_DEF_OUTPUT,                                                       /* GPIO mode : output only mode                     */
-    GPIO_MODE_OUTPUT_OD = ((GPIO_MODE_DEF_OUTPUT)|(GPIO_MODE_DEF_OD)),                             /* GPIO mode : output only with open-drain mode     */
-    GPIO_MODE_INPUT_OUTPUT_OD = ((GPIO_MODE_DEF_INPUT)|(GPIO_MODE_DEF_OUTPUT)|(GPIO_MODE_DEF_OD)), /* GPIO mode : output and input with open-drain mode*/
-    GPIO_MODE_INPUT_OUTPUT = ((GPIO_MODE_DEF_INPUT)|(GPIO_MODE_DEF_OUTPUT)),                       /* GPIO mode : output and input mode                */
+    GPIO_MODE_INPUT = GPIO_MODE_DEF_INPUT,                                                         /*!< GPIO mode : input only                           */
+    GPIO_MODE_OUTPUT = GPIO_MODE_DEF_OUTPUT,                                                       /*!< GPIO mode : output only mode                     */
+    GPIO_MODE_OUTPUT_OD = ((GPIO_MODE_DEF_OUTPUT)|(GPIO_MODE_DEF_OD)),                             /*!< GPIO mode : output only with open-drain mode     */
+    GPIO_MODE_INPUT_OUTPUT_OD = ((GPIO_MODE_DEF_INPUT)|(GPIO_MODE_DEF_OUTPUT)|(GPIO_MODE_DEF_OD)), /*!< GPIO mode : output and input with open-drain mode*/
+    GPIO_MODE_INPUT_OUTPUT = ((GPIO_MODE_DEF_INPUT)|(GPIO_MODE_DEF_OUTPUT)),                       /*!< GPIO mode : output and input mode                */
 } gpio_mode_t;

 typedef enum {
-    GPIO_PULLUP_DISABLE = 0x0,     /* disable GPIO pull-up resistor */
-    GPIO_PULLUP_ENABLE = 0x1,      /*  enable GPIO pull-up resistor */
+    GPIO_PULLUP_DISABLE = 0x0,     /*!< disable GPIO pull-up resistor */
+    GPIO_PULLUP_ENABLE = 0x1,      /*!< enable GPIO pull-up resistor */
 } gpio_pullup_t;

 typedef enum {
-    GPIO_PULLDOWN_DISABLE = 0x0,   /* disable GPIO pull-down resistor */
-    GPIO_PULLDOWN_ENABLE = 0x1,    /* enable GPIO pull-down resistor  */
+    GPIO_PULLDOWN_DISABLE = 0x0,   /*!< disable GPIO pull-down resistor */
+    GPIO_PULLDOWN_ENABLE = 0x1,    /*!< enable GPIO pull-down resistor  */
 } gpio_pulldown_t;

 typedef struct {
-    uint64_t pin_bit_mask;          /* GPIO pin: set with bit mask, each bit maps to a GPIO */
-    gpio_mode_t mode;               /* GPIO mode: set input/output mode                     */
-    gpio_pullup_t pull_up_en;       /* GPIO pull-up                                         */
-    gpio_pulldown_t pull_down_en;   /* GPIO pull-down                                       */
-    gpio_int_type_t intr_type;      /* GPIO interrupt type                                  */
+    uint64_t pin_bit_mask;          /*!< GPIO pin: set with bit mask, each bit maps to a GPIO */
+    gpio_mode_t mode;               /*!< GPIO mode: set input/output mode                     */
+    gpio_pullup_t pull_up_en;       /*!< GPIO pull-up                                         */
+    gpio_pulldown_t pull_down_en;   /*!< GPIO pull-down                                       */
+    gpio_int_type_t intr_type;      /*!< GPIO interrupt type                                  */
 } gpio_config_t;

 typedef enum {
@ -199,10 +199,10 @@ typedef enum {
 } gpio_level_t;

 typedef enum {
-    GPIO_PULLUP_ONLY,               /* Pad pull up            */
-    GPIO_PULLDOWN_ONLY,             /* Pad pull down          */
-    GPIO_PULLUP_PULLDOWN,           /* Pad pull up + pull down*/
-    GPIO_FLOATING,                  /* Pad floating           */
+    GPIO_PULLUP_ONLY,               /*!< Pad pull up            */
+    GPIO_PULLDOWN_ONLY,             /*!< Pad pull down          */
+    GPIO_PULLUP_PULLDOWN,           /*!< Pad pull up + pull down*/
+    GPIO_FLOATING,                  /*!< Pad floating           */
 } gpio_pull_mode_t;

 typedef void (*gpio_event_callback)(gpio_num_t gpio_intr_num);
@ -224,20 +224,20 @@ typedef void (*gpio_event_callback)(gpio_num_t gpio_intr_num);
 */

 /**
- * @brief	   GPIO common configuration
+ * @brief      GPIO common configuration
 *
 * Use this Function ,Configure GPIO's Mode,pull-up,PullDown,IntrType
 *
- * @parameter[in]  pGPIOConfig
- *                 pGPIOConfig.pin_bit_mask   : Configure GPIO pins bits,set this parameter with bit mask.
+ * @param[in]  pGPIOConfig
+ *             pGPIOConfig.pin_bit_mask   : Configure GPIO pins bits,set this parameter with bit mask.
 *                                              If you want to configure GPIO34 and GPIO16, pin_bit_mask=GPIO_Pin_16|GPIO_Pin_34;
- *                 pGPIOConfig.mode           : Configure GPIO mode,such as output ,input...
- *                 pGPIOConfig.pull_up_en     : Enable or Disable pull-up
- *                 pGPIOConfig.pull_down_en   : Enable or Disable pull-down
- *                 pGPIOConfig.intr_type : Configure GPIO interrupt trigger type
- * @return	       ESP_OK: success ;
- *                 ESP_ERR_INVALID_ARG: parameter error
- *                 ESP_FAIL : GPIO error
+ *             pGPIOConfig.mode           : Configure GPIO mode,such as output ,input...
+ *             pGPIOConfig.pull_up_en     : Enable or Disable pull-up
+ *             pGPIOConfig.pull_down_en   : Enable or Disable pull-down
+ *             pGPIOConfig.intr_type : Configure GPIO interrupt trigger type
+ * @return     ESP_OK: success ;
+ *             ESP_ERR_INVALID_ARG: parameter error
+ *             ESP_FAIL : GPIO error
 *
 */
 esp_err_t gpio_config(gpio_config_t *pGPIOConfig);
@ -246,12 +246,12 @@ esp_err_t gpio_config(gpio_config_t *pGPIOConfig);
 /**
 * @brief      GPIO set interrupt trigger type
 *
- * @parameter[in]  gpio_num : GPIO number.
+ * @param[in]  gpio_num : GPIO number.
 *                            If you want to set output level of GPIO16, gpio_num should be GPIO_NUM_16 (16);
- * @parameter[in]  intr_type: interrupt type, select from gpio_int_type_t
+ * @param[in]  intr_type: interrupt type, select from gpio_int_type_t
 *
- * @return         ESP_OK   : success
- *                 ESP_ERR_INVALID_ARG: parameter error
+ * @return     ESP_OK   : success
+ *             ESP_ERR_INVALID_ARG: parameter error
 *
 */
 esp_err_t gpio_set_intr_type(gpio_num_t gpio_num, gpio_int_type_t intr_type);
@ -259,11 +259,11 @@ esp_err_t gpio_set_intr_type(gpio_num_t gpio_num, gpio_int_type_t intr_type);
 /**
 * @brief      enable GPIO module interrupt signal
 *
- * @parameter[in]  gpio_num : GPIO number.
+ * @param[in]  gpio_num : GPIO number.
 *                            If you want to set output level of GPIO16, gpio_num should be GPIO_NUM_16 (16);
 *
- * @return         ESP_OK   : success
- *                 ESP_ERR_INVALID_ARG: parameter error
+ * @return     ESP_OK   : success
+ *             ESP_ERR_INVALID_ARG: parameter error
 *
 */
 esp_err_t gpio_intr_enable(gpio_num_t gpio_num);
@ -271,78 +271,78 @@ esp_err_t gpio_intr_enable(gpio_num_t gpio_num);
 /**
 * @brief      disable GPIO module interrupt signal
 *
- * @parameter[in]  gpio_num : GPIO number.
+ * @param[in]  gpio_num : GPIO number.
 *                            If you want to set output level of GPIO16, gpio_num should be GPIO_NUM_16 (16);
 *
- * @return         ESP_OK   : success
- *                 ESP_ERR_INVALID_ARG: parameter error
+ * @return     ESP_OK   : success
+ *             ESP_ERR_INVALID_ARG: parameter error
 *
 */
 esp_err_t gpio_intr_disable(gpio_num_t gpio_num);

 /**
- * @brief	   GPIO set output level
+ * @brief      GPIO set output level
 *
- * @parameter[in]  gpio_num : GPIO number.
+ * @param[in]  gpio_num : GPIO number.
 *                            If you want to set output level of GPIO16, gpio_num should be GPIO_NUM_16 (16);
- * @parameter[in]  level    : Output level. 0: low ; 1: high
+ * @param[in]  level    : Output level. 0: low ; 1: high
 *
- * @return	       ESP_OK   : success
- *                 ESP_FAIL : GPIO error
+ * @return     ESP_OK   : success
+ *             ESP_FAIL : GPIO error
 *
 */
 esp_err_t gpio_set_level(gpio_num_t gpio_num, uint32_t level);

 /**
- * @brief	   GPIO get input level
+ * @brief	GPIO get input level
 *
- * @parameter[in]  gpio_num : GPIO number.
+ * @param[in]  gpio_num : GPIO number.
 *                            If you want to get level of pin GPIO16, gpio_num should be GPIO_NUM_16 (16);
 *
- * @return	    0  : the GPIO input level is 0
+ * @return	0  : the GPIO input level is 0
 *              1  : the GPIO input level is 1
 *
 */
 int gpio_get_level(gpio_num_t gpio_num);

 /**
- * @brief	   GPIO set direction
+ * @brief      GPIO set direction
 *
 * Configure GPIO direction,such as output_only,input_only,output_and_input
 *
- * @parameter[in]  gpio_num : Configure GPIO pins number,it should be GPIO number.
+ * @param[in]  gpio_num : Configure GPIO pins number,it should be GPIO number.
 *                            If you want to set direction of GPIO16, gpio_num should be GPIO_NUM_16 (16);
- * @parameter[in]  mode     : Configure GPIO direction,such as output_only,input_only,...
+ * @param[in]  mode     : Configure GPIO direction,such as output_only,input_only,...
 *
- * @return	       ESP_OK   : success
- *                 ESP_ERR_INVALID_ARG : fail
- *                 ESP_FAIL : GPIO error
+ * @return     ESP_OK   : success
+ *             ESP_ERR_INVALID_ARG : fail
+ *             ESP_FAIL : GPIO error
 *
 */
 esp_err_t gpio_set_direction(gpio_num_t gpio_num, gpio_mode_t mode);

 /**
- * @brief	   GPIO set pull
+ * @brief	GPIO set pull
 *
 * User this Function,configure GPIO pull mode,such as pull-up,pull-down
 *
- * @parameter[in]  gpio_num : Configure GPIO pins number,it should be GPIO number.
+ * @param[in]  gpio_num : Configure GPIO pins number,it should be GPIO number.
 *                            If you want to set pull up or down mode for GPIO16,gpio_num should be GPIO_NUM_16 (16);
- * @parameter[in]  pull     : Configure GPIO pull up/down mode,such as pullup_only,pulldown_only,pullup_and_pulldown,...
+ * @param[in]  pull     : Configure GPIO pull up/down mode,such as pullup_only,pulldown_only,pullup_and_pulldown,...
 *
- * @return	       ESP_OK   : success
- *                 ESP_ERR_INVALID_ARG : fail
- *                 ESP_FAIL : GPIO error
+ * @return	ESP_OK   : success
+ *              ESP_ERR_INVALID_ARG : fail
+ *              ESP_FAIL : GPIO error
 *
 */
 esp_err_t gpio_set_pull_mode(gpio_num_t gpio_num, gpio_pull_mode_t pull);

 /**
-  * @brief enable GPIO wake-up function.
+  * @brief  enable GPIO wake-up function.
  *
-  * @param gpio_num_t gpio_num : GPIO number.
+  * @param  gpio_num : GPIO number.
  *
-  * @param gpio_int_type_t intr_type : only GPIO_INTR_LOLEVEL\GPIO_INTR_HILEVEL can be used
+  * @param  intr_type : only GPIO_INTR_LOLEVEL\GPIO_INTR_HILEVEL can be used
  *
  * @return ESP_OK: success
  *         ESP_ERR_INVALID_ARG: parameter error
@ -350,9 +350,9 @@ esp_err_t gpio_set_pull_mode(gpio_num_t gpio_num, gpio_pull_mode_t pull);
 esp_err_t gpio_wakeup_enable(gpio_num_t gpio_num, gpio_int_type_t intr_type);

 /**
-  * @brief disable GPIO wake-up function.
+  * @brief  disable GPIO wake-up function.
  *
-  * @param gpio_num_t gpio_num: GPIO number
+  * @param  gpio_num: GPIO number
  *
  * @return ESP_OK: success
  *         ESP_ERR_INVALID_ARG: parameter error
@ -365,13 +365,13 @@ esp_err_t gpio_wakeup_disable(gpio_num_t gpio_num);
 *          Users should know that which CPU is running and then pick a INUM that is not used by system.
 *          We can find the information of INUM and interrupt level in soc.h.
 *          TODO: to move INUM options to menu_config
- * @parameter   uint32_t gpio_intr_num     : GPIO interrupt number,check the info in soc.h, and please see the core-isa.h for more details
- * @parameter   void (* fn)(void* )       : interrupt handler function.
+ * @param   gpio_intr_num    : GPIO interrupt number,check the info in soc.h, and please see the core-isa.h for more details
+ * @param   (*fn)(void* )    : interrupt handler function.
 *                                          Note that the handler function MUST be defined with attribution of "IRAM_ATTR".
- * @parameter   void * arg                : parameter for handler function
+ * @param   arg              : parameter for handler function
 *
- * @return      ESP_OK : success ;
- *              ESP_FAIL: gpio error
+ * @return  ESP_OK : success ;
+ *          ESP_FAIL: gpio error
 */
 esp_err_t gpio_isr_register(uint32_t gpio_intr_num, void (*fn)(void*), void * arg);

--- a/components/log/README.rst
+++ b/components/log/README.rst
@ -0,0 +1,61 @@
+Logging library
+===============
+
+Overview
+--------
+
+Log library has two ways of managing log verbosity: compile time, set via menuconfig; and runtime, using ``esp_log_set_level`` function.
+
+At compile time, filtering is done using ``CONFIG_LOG_DEFAULT_LEVEL`` macro, set via menuconfig. All logging statments for levels higher than ``CONFIG_LOG_DEFAULT_LEVEL`` will be removed by the preprocessor.
+
+At run time, all logs below ``CONFIG_LOG_DEFAULT_LEVEL`` are enabled by default. ``esp_log_set_level`` function may be used to set logging level per module. Modules are identified by their tags, which are human-readable ASCII zero-terminated strings.
+
+How to use this library
+-----------------------
+
+In each C file which uses logging functionality, define TAG variable like this:
+
+.. code-block:: c
+
+   static const char* TAG = "MyModule";
+
+then use one of logging macros to produce output, e.g:
+
+.. code-block:: c
+
+   ESP_LOGW(TAG, "Baud rate error %.1f%%. Requested: %d baud, actual: %d baud", error * 100, baud_req, baud_real);
+
+Several macros are available for different verbosity levels:
+
+* ``ESP_LOGE`` - error
+* ``ESP_LOGW`` - warning
+* ``ESP_LOGI`` - info
+* ``ESP_LOGD`` - debug
+* ``ESP_LOGV`` - verbose
+
+Additionally there is an _EARLY_ variant for each of these macros (e.g. ``ESP_EARLY_LOGE`` ).These variants can run in startup code, before heap allocator and syscalls have been initialized. When compiling bootloader, normal ``ESP_LOGx`` macros fall back to the same implementation as ``ESP_EARLY_LOGx`` macros. So the only place where ``ESP_EARLY_LOGx`` have to be used explicitly is the early startup code, such as heap allocator initialization code.
+
+(Note that such distinction would not have been necessary if we would have an ``ets_vprintf`` function in the ROM. Then it would be possible to switch implementation from _EARLY_ version to normal version on the fly. Unfortunately, ``ets_vprintf`` in ROM has been inlined by the compiler into ``ets_printf``, so it is not accessible outside.)
+
+To override default verbosity level at file or component scope, define ``LOG_LOCAL_LEVEL`` macro. At file scope, define it before including ``esp_log.h``, e.g.:
+
+.. code-block:: c
+
+   #define LOG_LOCAL_LEVEL ESP_LOG_VERBOSE
+   #include "esp_log.h"
+
+
+At component scope, define it in component makefile:
+
+.. code-block:: make
+
+   CFLAGS += -D LOG_LOCAL_LEVEL=ESP_LOG_DEBUG
+
+To configure logging output per module at runtime, add calls to ``esp_log_set_level`` function:
+
+.. code-block:: c
+
+   esp_log_set_level("*", ESP_LOG_ERROR);        // set all components to ERROR level
+   esp_log_set_level("wifi", ESP_LOG_WARN);      // enable WARN logs from WiFi stack
+   esp_log_set_level("dhcpc", ESP_LOG_INFO);     // enable INFO logs from DHCP client
+
--- a/components/log/include/esp_log.h
+++ b/components/log/include/esp_log.h
@ -24,76 +24,16 @@ extern "C" {
 #endif

 /**
- * @brief Logging library
- *
- * Log library has two ways of managing log verbosity: compile time, set via
- * menuconfig, and runtime, using esp_log_set_level function.
- *
- * At compile time, filtering is done using CONFIG_LOG_DEFAULT_LEVEL macro, set via
- * menuconfig. All logging statments for levels higher than CONFIG_LOG_DEFAULT_LEVEL
- * will be removed by the preprocessor.
- *
- * At run time, all logs below CONFIG_LOG_DEFAULT_LEVEL are enabled by default.
- * esp_log_set_level function may be used to set logging level per module.
- * Modules are identified by their tags, which are human-readable ASCII
- * zero-terminated strings.
- *
- * How to use this library:
- *
- * In each C file which uses logging functionality, define TAG variable like this:
- *
- *      static const char* TAG = "MyModule";
- *
- * then use one of logging macros to produce output, e.g:
- *
- *      ESP_LOGW(TAG, "Baud rate error %.1f%%. Requested: %d baud, actual: %d baud", error * 100, baud_req, baud_real);
- *
- * Several macros are available for different verbosity levels:
- *
- *      ESP_LOGE — error
- *      ESP_LOGW — warning
- *      ESP_LOGI — info
- *      ESP_LOGD - debug
- *      ESP_LOGV - verbose
- *
- * Additionally there is an _EARLY_ variant for each of these macros (e.g. ESP_EARLY_LOGE).
- * These variants can run in startup code, before heap allocator and syscalls
- * have been initialized.
- * When compiling bootloader, normal ESP_LOGx macros fall back to the same implementation
- * as ESP_EARLY_LOGx macros. So the only place where ESP_EARLY_LOGx have to be used explicitly
- * is the early startup code, such as heap allocator initialization code.
- *
- * (Note that such distinction would not have been necessary if we would have an
- * ets_vprintf function in the ROM. Then it would be possible to switch implementation
- * from _EARLY version to normal version on the fly. Unfortunately, ets_vprintf in ROM
- * has been inlined by the compiler into ets_printf, so it is not accessible outside.)
- *
- * To override default verbosity level at file or component scope, define LOG_LOCAL_LEVEL macro.
- * At file scope, define it before including esp_log.h, e.g.:
- *
- *      #define LOG_LOCAL_LEVEL ESP_LOG_VERBOSE
- *      #include "esp_log.h"
- *
- * At component scope, define it in component makefile:
- *
- *      CFLAGS += -D LOG_LOCAL_LEVEL=ESP_LOG_DEBUG
- *
- * To configure logging output per module at runtime, add calls to esp_log_set_level function:
- *
- *      esp_log_set_level("*", ESP_LOG_ERROR);        // set all components to ERROR level
- *      esp_log_set_level("wifi", ESP_LOG_WARN);      // enable WARN logs from WiFi stack
- *      esp_log_set_level("dhcpc", ESP_LOG_INFO);     // enable INFO logs from DHCP client
+ * @brief Log level
 *
 */
-
-
 typedef enum {
-    ESP_LOG_NONE,       // No log output
-    ESP_LOG_ERROR,      // Critical errors, software module can not recover on its own
-    ESP_LOG_WARN,       // Error conditions from which recovery measures have been taken
-    ESP_LOG_INFO,       // Information messages which describe normal flow of events
-    ESP_LOG_DEBUG,      // Extra information which is not necessary for normal use (values, pointers, sizes, etc).
-    ESP_LOG_VERBOSE     // Bigger chunks of debugging information, or frequent messages which can potentially flood the output.
+    ESP_LOG_NONE,       /*!< No log output */
+    ESP_LOG_ERROR,      /*!< Critical errors, software module can not recover on its own */
+    ESP_LOG_WARN,       /*!< Error conditions from which recovery measures have been taken */
+    ESP_LOG_INFO,       /*!< Information messages which describe normal flow of events */
+    ESP_LOG_DEBUG,      /*!< Extra information which is not necessary for normal use (values, pointers, sizes, etc). */
+    ESP_LOG_VERBOSE     /*!< Bigger chunks of debugging information, or frequent messages which can potentially flood the output. */
 } esp_log_level_t;

 typedef int (*vprintf_like_t)(const char *, va_list);
@ -120,17 +60,6 @@ void esp_log_level_set(const char* tag, esp_log_level_t level);
 */
 void esp_log_set_vprintf(vprintf_like_t func);

-/**
- * @brief Write message into the log
- *
- * This function is not intended to be used directly. Instead, use one of
- * ESP_LOGE, ESP_LOGW, ESP_LOGI, ESP_LOGD, ESP_LOGV macros.
- *
- * This function or these macros should not be used from an interrupt.
- */
-void esp_log_write(esp_log_level_t level, const char* tag, const char* format, ...) __attribute__ ((format (printf, 3, 4)));
-
-
 /**
 * @brief Function which returns timestamp to be used in log output
 *
@ -143,7 +72,17 @@ void esp_log_write(esp_log_level_t level, const char* tag, const char* format, .
 *
 * @return timestamp, in milliseconds
 */
-uint32_t esp_log_timestamp();
+uint32_t esp_log_timestamp(void);
+
+/**
+ * @brief Write message into the log
+ *
+ * This function is not intended to be used directly. Instead, use one of
+ * ESP_LOGE, ESP_LOGW, ESP_LOGI, ESP_LOGD, ESP_LOGV macros.
+ *
+ * This function or these macros should not be used from an interrupt.
+ */
+void esp_log_write(esp_log_level_t level, const char* tag, const char* format, ...) __attribute__ ((format (printf, 3, 4)));


 #if CONFIG_LOG_COLORS
--- a/components/nvs_flash/README.rst
+++ b/components/nvs_flash/README.rst
@ -7,14 +7,14 @@ Introduction
 Non-volatile storage (NVS) library is designed to store key-value pairs in flash. This sections introduces some concepts used by NVS.

 Underlying storage
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^

 Currently NVS uses a portion of main flash memory through ``spi_flash_{read|write|erase}`` APIs. The range of flash sectors to be used by the library is provided to ``nvs_flash_init`` function.

 Future versions of this library may add other storage backends to keep data in another flash chip (SPI or I2C), RTC, FRAM, etc.

 Keys and values
-~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^

 NVS operates on key-value pairs. Keys are ASCII strings, maximum key length is currently 15 characters. Values can have one of the following types:

@ -32,12 +32,12 @@ Keys are required to be unique. Writing a value for a key which already exists b
 Data type check is also performed when reading a value. An error is returned if data type of read operation doesn’t match the data type of the value.

 Namespaces
-~~~~~~~~~~
+^^^^^^^^^^

 To mitigate potential conflicts in key names between different components, NVS assigns each key-value pair to one of namespaces. Namespace names follow the same rules as key names, i.e. 15 character maximum length. Namespace name is specified in the ``nvs_open`` call. This call returns an opaque handle, which is used in subsequent calls to ``nvs_read_*``, ``nvs_write_*``, and ``nvs_commit`` functions. This way, handle is associated with a namespace, and key names will not collide with same names in other namespaces.

 Security, tampering, and robustness
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

 NVS library doesn't implement tamper prevention measures. It is possible for anyone with physical access to the flash chip to alter, erase, or add key-value pairs.

@ -59,12 +59,12 @@ Internals
 ---------

 Log of key-value pairs
-~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^

 NVS stores key-value pairs sequentially, with new key-value pairs being added at the end. When a value of any given key has to be updated, new key-value pair is added at the end of the log and old key-value pair is marked as erased.

 Pages and entries
-~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^

 NVS library uses two main entities in its operation: pages and entries. Page is a logical structure which stores a portion of the overall log. Logical page corresponds to one physical sector of flash memory. Pages which are in use have a *sequence number* associated with them. Sequence numbers impose an ordering on pages. Higher sequence numbers correspond to pages which were created later. Each page can be in one of the following states:

@ -101,7 +101,7 @@ Mapping from flash sectors to logical pages doesn't have any particular order. L
    +----------+  +----------+  +----------+  +----------+

 Structure of a page
-~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^

 For now we assume that flash sector size is 4096 bytes and that ESP32 flash encryption hardware operates on 32-byte blocks. It is possible to introduce some settings configurable at compile-time (e.g. via menuconfig) to accommodate flash chips with different sector sizes (although it is not clear if other components in the system, e.g. SPI flash driver and SPI flash cache can support these other sizes).

@ -133,7 +133,7 @@ CRC32 value in header is calculated over the part which doesn't include state va
 The following sections describe structure of entry state bitmap and entry itself.

 Entry and entry state bitmap
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^

 Each entry can be in one of the following three states. Each state is represented with two bits in the entry state bitmap. Final four bits in the bitmap (256 - 2 * 126) are unused.

@ -148,7 +148,7 @@ Erased (2'b00)


 Structure of entry
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^

 For values of primitive types (currently integers from 1 to 8 bytes long), entry holds one key-value pair. For string and blob types, entry holds part of the whole key-value pair. In case when a key-value pair spans multiple entries, all entries are stored in the same page.

@ -200,7 +200,7 @@ Variable length values (strings and blobs) are written into subsequent entries,


 Namespaces
-~~~~~~~~~~
+^^^^^^^^^^

 As mentioned above, each key-value pair belongs to one of the namespaces. Namespaces identifiers (strings) are stored as keys of key-value pairs in namespace with index 0. Values corresponding to these keys are indexes of these namespaces. 

@ -218,10 +218,9 @@ As mentioned above, each key-value pair belongs to one of the namespaces. Namesp


 Item hash list
-~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^

 To reduce the number of reads performed from flash memory, each member of Page class maintains a list of pairs: (item index; item hash). This list makes searches much quicker. Instead of iterating over all entries, reading them from flash one at a time, ``Page::findItem`` first performs search for item hash in the hash list. This gives the item index within the page, if such an item exists. Due to a hash collision it is possible that a different item will be found. This is handled by falling back to iteration over items in flash.

 Each node in hash list contains a 24-bit hash and 8-bit item index. Hash is calculated based on item namespace and key name. CRC32 is used for calculation, result is truncated to 24 bits. To reduce overhead of storing 32-bit entries in a linked list, list is implemented as a doubly-linked list of arrays. Each array holds 29 entries, for the total size of 128 bytes, together with linked list pointers and 32-bit count field. Minimal amount of extra RAM useage per page is therefore 128 bytes, maximum is 640 bytes.

-
--- a/components/nvs_flash/include/nvs.h
+++ b/components/nvs_flash/include/nvs.h
@ -28,23 +28,27 @@ extern "C" {
 */
 typedef uint32_t nvs_handle;

-#define ESP_ERR_NVS_BASE                0x1100
-#define ESP_ERR_NVS_NOT_INITIALIZED     (ESP_ERR_NVS_BASE + 0x01)
-#define ESP_ERR_NVS_NOT_FOUND           (ESP_ERR_NVS_BASE + 0x02)
-#define ESP_ERR_NVS_TYPE_MISMATCH       (ESP_ERR_NVS_BASE + 0x03)
-#define ESP_ERR_NVS_READ_ONLY           (ESP_ERR_NVS_BASE + 0x04)
-#define ESP_ERR_NVS_NOT_ENOUGH_SPACE    (ESP_ERR_NVS_BASE + 0x05)
-#define ESP_ERR_NVS_INVALID_NAME        (ESP_ERR_NVS_BASE + 0x06)
-#define ESP_ERR_NVS_INVALID_HANDLE      (ESP_ERR_NVS_BASE + 0x07)
-#define ESP_ERR_NVS_REMOVE_FAILED       (ESP_ERR_NVS_BASE + 0x08)
-#define ESP_ERR_NVS_KEY_TOO_LONG        (ESP_ERR_NVS_BASE + 0x09)
-#define ESP_ERR_NVS_PAGE_FULL           (ESP_ERR_NVS_BASE + 0x0a)
-#define ESP_ERR_NVS_INVALID_STATE       (ESP_ERR_NVS_BASE + 0x0b)
-#define ESP_ERR_NVS_INVALID_LENGTH      (ESP_ERR_NVS_BASE + 0x0c)
+#define ESP_ERR_NVS_BASE                0x1100                     /*!< Starting number of error codes */
+#define ESP_ERR_NVS_NOT_INITIALIZED     (ESP_ERR_NVS_BASE + 0x01)  /*!< The storage driver is not initialized */
+#define ESP_ERR_NVS_NOT_FOUND           (ESP_ERR_NVS_BASE + 0x02)  /*!< Id namespace doesn’t exist yet and mode is NVS_READONLY */
+#define ESP_ERR_NVS_TYPE_MISMATCH       (ESP_ERR_NVS_BASE + 0x03)  /*!< TBA */
+#define ESP_ERR_NVS_READ_ONLY           (ESP_ERR_NVS_BASE + 0x04)  /*!< Storage handle was opened as read only */
+#define ESP_ERR_NVS_NOT_ENOUGH_SPACE    (ESP_ERR_NVS_BASE + 0x05)  /*!< There is not enough space in the underlying storage to save the value */
+#define ESP_ERR_NVS_INVALID_NAME        (ESP_ERR_NVS_BASE + 0x06)  /*!< Namespace name doesn’t satisfy constraints */
+#define ESP_ERR_NVS_INVALID_HANDLE      (ESP_ERR_NVS_BASE + 0x07)  /*!< Handle has been closed or is NULL */
+#define ESP_ERR_NVS_REMOVE_FAILED       (ESP_ERR_NVS_BASE + 0x08)  /*!< The value wasn’t updated because flash write operation has failed. The value was written however, and update will be finished after re-initialization of nvs, provided that flash operation doesn’t fail again. */
+#define ESP_ERR_NVS_KEY_TOO_LONG        (ESP_ERR_NVS_BASE + 0x09)  /*!< TBA */
+#define ESP_ERR_NVS_PAGE_FULL           (ESP_ERR_NVS_BASE + 0x0a)  /*!< TBA */
+#define ESP_ERR_NVS_INVALID_STATE       (ESP_ERR_NVS_BASE + 0x0b)  /*!< TBA */
+#define ESP_ERR_NVS_INVALID_LENGTH      (ESP_ERR_NVS_BASE + 0x0c)  /*!< TBA */

+/**
+ * @brief Mode of opening the non-volatile storage
+ *
+ */
 typedef enum {
-	NVS_READONLY,
-	NVS_READWRITE
+	NVS_READONLY,  /*!< Read only */
+	NVS_READWRITE  /*!< Read and write */
 } nvs_open_mode;

 /**
@ -58,12 +62,13 @@ typedef enum {
 *                         underlying implementation, but is guaranteed to be
 *                         at least 16 characters. Shouldn't be empty.
 * @param[in]  open_mode   NVS_READWRITE or NVS_READONLY. If NVS_READONLY, will 
- *						   open a handle for reading only. All write requests will 
- *						   be rejected for this handle.
+ *                         open a handle for reading only. All write requests will 
+ *			   be rejected for this handle.
 * @param[out] out_handle  If successful (return code is zero), handle will be
 *                         returned in this argument.
 *
- * @return     - ESP_OK if storage handle was opened successfully
+ * @return
+ *             - ESP_OK if storage handle was opened successfully
 *             - ESP_ERR_NVS_NOT_INITIALIZED if the storage driver is not initialized
 *             - ESP_ERR_NVS_NOT_FOUND id namespace doesn't exist yet and
 *               mode is NVS_READONLY
@ -86,7 +91,8 @@ esp_err_t nvs_open(const char* name, nvs_open_mode open_mode, nvs_handle *out_ha
 * @param[in]  value   The value to set.
 * @param[in]  length  For nvs_set_blob: length of binary value to set, in bytes.
 *
- * @return     - ESP_OK if value was set successfully
+ * @return
+ *             - ESP_OK if value was set successfully
 *             - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
 *             - ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only
 *             - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints
@ -129,24 +135,26 @@ esp_err_t nvs_set_blob(nvs_handle handle, const char* key, const void* value, si
 * It is suggested that nvs_get/set_str is used for zero-terminated C strings, and
 * nvs_get/set_blob used for arbitrary data structures.
 *
- * Example of using nvs_get_i32:
+ * \code{c}
+ * // Example of using nvs_get_i32:
 * int32_t max_buffer_size = 4096; // default value
 * esp_err_t err = nvs_get_i32(my_handle, "max_buffer_size", &max_buffer_size);
 * assert(err == ESP_OK || err == ESP_ERR_NVS_NOT_FOUND);
 * // if ESP_ERR_NVS_NOT_FOUND was returned, max_buffer_size will still
 * // have its default value.
 *
- * Example (without error checking) of using nvs_get_str to get a string into dynamic array:
+ * // Example (without error checking) of using nvs_get_str to get a string into dynamic array:
 * size_t required_size;
 * nvs_get_str(my_handle, "server_name", NULL, &required_size);
 * char* server_name = malloc(required_size);
 * nvs_get_str(my_handle, "server_name", server_name, &required_size);
 *
- * Example (without error checking) of using nvs_get_blob to get a binary data
+ * // Example (without error checking) of using nvs_get_blob to get a binary data
 * into a static array:
 * uint8_t mac_addr[6];
 * size_t size = sizeof(mac_addr);
 * nvs_get_blob(my_handle, "dst_mac_addr", mac_addr, &size);
+ * \endcode
 *
 * @param[in]     handle     Handle obtained from nvs_open function.
 * @param[in]     key        Key name. Maximal length is determined by the underlying
@ -162,7 +170,8 @@ esp_err_t nvs_set_blob(nvs_handle handle, const char* key, const void* value, si
 *                           zero, will be set to the actual length of the value
 *                           written. For nvs_get_str this includes zero terminator.
 *
- * @return     - ESP_OK if the value was retrieved successfully
+ * @return
+ *             - ESP_OK if the value was retrieved successfully
 *             - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist
 *             - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
 *             - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints
@ -191,7 +200,8 @@ esp_err_t nvs_get_blob(nvs_handle handle, const char* key, void* out_value, size
 *                     implementation, but is guaranteed to be at least
 *                     16 characters. Shouldn't be empty.
 *
- * @return      - ESP_OK if erase operation was successful
+ * @return
+ *              - ESP_OK if erase operation was successful
 *              - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
 *              - ESP_ERR_NVS_READ_ONLY if handle was opened as read only
 *              - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist
@ -207,7 +217,8 @@ esp_err_t nvs_erase_key(nvs_handle handle, const char* key);
 * @param[in]  handle  Storage handle obtained with nvs_open.
 *                     Handles that were opened read only cannot be used.
 *
- * @return      - ESP_OK if erase operation was successful
+ * @return
+ *              - ESP_OK if erase operation was successful
 *              - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
 *              - ESP_ERR_NVS_READ_ONLY if handle was opened as read only
 *              - other error codes from the underlying storage driver
@ -224,7 +235,8 @@ esp_err_t nvs_erase_all(nvs_handle handle);
 * @param[in]  handle  Storage handle obtained with nvs_open.
 *                     Handles that were opened read only cannot be used.
 *
- * @return     - ESP_OK if the changes have been written successfully
+ * @return
+ *             - ESP_OK if the changes have been written successfully
 *             - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
 *             - other error codes from the underlying storage driver
 */
@ -249,3 +261,4 @@ void nvs_close(nvs_handle handle);
 #endif

 #endif //ESP_NVS_H
+
--- a/components/nvs_flash/include/nvs_flash.h
+++ b/components/nvs_flash/include/nvs_flash.h
@ -22,6 +22,8 @@ extern "C" {

    Temporarily, this region is hardcoded as a 12KB (0x3000 byte)
    region starting at 24KB (0x6000 byte) offset in flash.
+
+    @return ESP_OK if flash was successfully initialised.
 */
 esp_err_t nvs_flash_init(void);

--- a/docs/COPYRIGHT.rst
+++ b/docs/COPYRIGHT.rst
@ -1,3 +1,6 @@
+Copyrights and Licenses
+***********************
+
 Software Copyrights
 ===================

@ -87,8 +90,7 @@ developments under license policy of following terms.
 Copyright (C) 2011, ChaN, all right reserved.

 * The TJpgDec module is a free software and there is NO WARRANTY.
-* No restriction on use. You can use, modify and redistribute it for
-personal, non-profit or commercial products UNDER YOUR RESPONSIBILITY.
+* No restriction on use. You can use, modify and redistribute it for personal, non-profit or commercial products UNDER YOUR RESPONSIBILITY.
 * Redistributions of source code must retain the above copyright notice.


--- a/docs/Doxyfile
+++ b/docs/Doxyfile
@ -0,0 +1,22 @@
+PROJECT_NAME = "ESP32 Programming Guide"
+
+INPUT = ../components/esp32/include/esp_wifi.h ../components/driver/include/driver ../components/esp32/include/rom/gpio.h ../components/bt/include ../components/nvs_flash/include ../components/log/include ../components/vfs/include
+
+WARN_NO_PARAMDOC	= YES
+
+RECURSIVE		= NO
+CASE_SENSE_NAMES 	= NO
+EXTRACT_ALL		= NO
+
+GENERATE_XML		= YES
+XML_OUTPUT		= xml
+
+GENERATE_HTML		= NO
+HAVE_DOT		= NO
+GENERATE_LATEX		= NO
+GENERATE_MAN		= NO
+GENERATE_RTF		= NO
+
+QUIET = YES
+WARN_LOGFILE = "doxygen-warning-log.txt"
+
--- a/docs/Makefile
+++ b/docs/Makefile
@ -0,0 +1,177 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/ReadtheDocsTemplate.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/ReadtheDocsTemplate.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/ReadtheDocsTemplate"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/ReadtheDocsTemplate"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
--- a/docs/_static/doc-code-documentation-inline.png
+++ b/docs/_static/doc-code-documentation-inline.png
--- a/docs/_static/doc-code-documentation-rendered.png
+++ b/docs/_static/doc-code-documentation-rendered.png
--- a/docs/_static/doc-code-function.png
+++ b/docs/_static/doc-code-function.png
--- a/docs/_static/doc-code-member.png
+++ b/docs/_static/doc-code-member.png
--- a/docs/_static/doc-code-void-function.png
+++ b/docs/_static/doc-code-void-function.png
--- a/docs/api/bt.rst
+++ 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
+^^^^^^^^^^^^^^^^
+
+.. doxygenstruct:: 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
+
--- a/docs/api/esp_wifi.rst
+++ b/docs/api/esp_wifi.rst
@ -0,0 +1,74 @@
+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
+------
+
+.. doxygendefine:: WIFI_INIT_CONFIG_DEFAULT
+
+
+Typedefs
+--------
+
+.. doxygentypedef:: wifi_promiscuous_cb_t
+.. doxygentypedef:: wifi_rxcb_t
+.. doxygentypedef:: esp_vendor_ie_cb_t
+
+
+Functions
+---------
+
+.. doxygenfunction:: esp_wifi_init
+.. doxygenfunction:: esp_wifi_deinit
+.. doxygenfunction:: esp_wifi_set_mode
+.. doxygenfunction:: esp_wifi_get_mode
+.. doxygenfunction:: esp_wifi_start
+.. doxygenfunction:: esp_wifi_stop
+.. doxygenfunction:: esp_wifi_connect
+.. doxygenfunction:: esp_wifi_disconnect
+.. doxygenfunction:: esp_wifi_clear_fast_connect
+.. doxygenfunction:: esp_wifi_kick_station
+.. doxygenfunction:: esp_wifi_scan_start
+.. doxygenfunction:: esp_wifi_scan_stop
+.. doxygenfunction:: esp_wifi_get_ap_num
+.. doxygenfunction:: esp_wifi_get_ap_list
+.. doxygenfunction:: esp_wifi_set_ps
+.. doxygenfunction:: esp_wifi_get_ps
+.. doxygenfunction:: esp_wifi_set_protocol
+.. doxygenfunction:: esp_wifi_get_protocol
+.. doxygenfunction:: esp_wifi_set_bandwidth
+.. doxygenfunction:: esp_wifi_get_bandwidth
+.. doxygenfunction:: esp_wifi_set_channel
+.. doxygenfunction:: esp_wifi_get_channel
+.. doxygenfunction:: esp_wifi_set_country
+.. doxygenfunction:: esp_wifi_get_country
+.. doxygenfunction:: esp_wifi_set_mac
+.. doxygenfunction:: esp_wifi_get_mac
+.. doxygenfunction:: esp_wifi_set_promiscuous_rx_cb
+.. doxygenfunction:: esp_wifi_set_promiscuous
+.. doxygenfunction:: esp_wifi_get_promiscuous
+.. doxygenfunction:: esp_wifi_set_config
+.. doxygenfunction:: esp_wifi_get_config
+.. doxygenfunction:: esp_wifi_get_station_list
+.. doxygenfunction:: esp_wifi_free_station_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
+.. doxygenfunction:: esp_wifi_set_vendor_ie_cb
--- a/docs/api/gpio.rst
+++ b/docs/api/gpio.rst
@ -0,0 +1,90 @@
+GPIO 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>`_
+
+Enumerations
+^^^^^^^^^^^^
+
+.. doxygenenum:: gpio_int_type_t
+.. doxygenenum:: gpio_mode_t
+.. doxygenenum:: gpio_pull_mode_t
+
+Functions
+^^^^^^^^^
+
+.. doxygenfunction:: gpio_config
+.. doxygenfunction:: gpio_set_intr_type
+.. doxygenfunction:: gpio_intr_enable
+.. doxygenfunction:: gpio_intr_disable
+.. doxygenfunction:: gpio_set_level
+.. doxygenfunction:: gpio_get_level
+.. doxygenfunction:: gpio_set_direction
+.. doxygenfunction:: gpio_set_pull_mode
+.. doxygenfunction:: gpio_wakeup_enable
+.. doxygenfunction:: gpio_wakeup_disable
+.. doxygenfunction:: gpio_isr_register
+
+*Example code:* Configuration of GPIO as an output
+
+.. code-block:: c
+
+    gpio_config_t io_conf;
+    io_conf.intr_type = GPIO_INTR_DISABLE;             //disable interrupt
+    io_conf.mode = GPIO_MODE_OUTPUT;                   //set as output mode
+    io_conf.pin_bit_mask = GPIO_SEL_18 | GPIO_SEL_19;  //bit mask of the pins that you want to set,e.g.GPIO18/19
+    io_conf.pull_down_en = 0;                          //disable pull-down mode
+    io_conf.pull_up_en = 0;                            //disable pull-up mode
+    gpio_config(&io_conf);                             //configure GPIO with the given settings
+
+*Example code:* Configuration of GPIO as an input
+
+.. code-block:: c
+
+    gpio_config_t io_conf;
+    io_conf.intr_type = GPIO_INTR_POSEDGE;             //set posedge interrupt
+    io_conf.mode = GPIO_MODE_INPUT;                    //set as input
+    io_conf.pin_bit_mask = GPIO_SEL_4 | GPIO_SEL_5;    //bit mask of the pins that you want to set, e.g.,GPIO4/5
+    io_conf.pull_down_en = 0;                          //disable pull-down mode
+    io_conf.pull_up_en = 1;                            //enable pull-up mode
+    gpio_config(&io_conf);                             //configure GPIO with the given settings
+
+
+ROM GPIO functions
+^^^^^^^^^^^^^^^^^^
+
+.. doxygenfunction:: gpio_init
+.. doxygenfunction:: gpio_output_set
+.. doxygenfunction:: gpio_output_set_high
+.. doxygenfunction:: gpio_input_get
+.. doxygenfunction:: gpio_input_get_high
+.. doxygenfunction:: gpio_intr_handler_register
+.. doxygenfunction:: gpio_intr_pending
+.. doxygenfunction:: gpio_intr_pending_high
+.. doxygenfunction:: gpio_intr_ack
+.. doxygenfunction:: gpio_intr_ack_high
+.. doxygenfunction:: gpio_pin_wakeup_enable
+.. doxygenfunction:: gpio_pin_wakeup_disable
+.. doxygenfunction:: gpio_matrix_in
+.. doxygenfunction:: gpio_matrix_out
+.. doxygenfunction:: gpio_pad_select_gpio
+.. doxygenfunction:: gpio_pad_set_drv
+.. doxygenfunction:: gpio_pad_pullup
+.. doxygenfunction:: gpio_pad_pulldown
+.. doxygenfunction:: gpio_pad_unhold
+.. doxygenfunction:: gpio_pad_hold
+
+
--- a/docs/api/log.rst
+++ b/docs/api/log.rst
@ -0,0 +1,19 @@
+.. include:: ../../components/log/README.rst
+
+API Reference
+-------------
+
+Enumerations
+^^^^^^^^^^^^
+
+.. doxygenenum:: esp_log_level_t
+
+Functions
+^^^^^^^^^
+
+.. doxygenfunction:: esp_log_level_set
+.. doxygenfunction:: esp_log_set_vprintf
+.. doxygenfunction:: esp_log_timestamp
+.. doxygenfunction:: esp_log_write
+
+
--- a/docs/api/nvs.rst
+++ b/docs/api/nvs.rst
@ -0,0 +1,68 @@
+.. 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
+
+
+
--- a/docs/api/template.rst
+++ b/docs/api/template.rst
@ -0,0 +1,70 @@
+Template API
+=============
+
+Overview
+--------
+
+INSTRUCTIONS: Provide overview where and how this API may be used. For large number of functions, break down description into groups.
+
+Use the folowing heading levels:
+
+* # with overline, for parts
+* \* with overline, for chapters
+* =, for sections
+* -, for subsections
+* ^, for subsubsections
+* ", for paragraphs
+
+
+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
+
+
--- a/docs/api/vfs.rst
+++ b/docs/api/vfs.rst
@ -0,0 +1,27 @@
+.. include:: ../../components/vfs/README.rst
+
+API Reference
+-------------
+
+Defines
+^^^^^^^
+
+.. doxygendefine:: ESP_VFS_PATH_MAX 
+.. doxygendefine:: ESP_VFS_FLAG_DEFAULT
+.. doxygendefine:: ESP_VFS_FLAG_CONTEXT_PTR 
+
+
+Structures
+^^^^^^^^^^
+
+.. doxygenstruct:: esp_vfs_t
+
+Functions
+^^^^^^^^^
+
+.. doxygenfunction:: esp_vfs_dev_uart_register
+.. doxygenfunction:: esp_vfs_register
+
+
+
+
--- a/docs/build_system.rst
+++ b/docs/build_system.rst
@ -1,5 +1,5 @@
 Build System
------------
+************

 This document explains the Espressif IoT Development Framework build system and the
 concept of "components"
--- a/docs/conf.py
+++ b/docs/conf.py
@ -0,0 +1,301 @@
+# -*- coding: utf-8 -*-
+#
+# Read the Docs Template documentation build configuration file, created by
+# sphinx-quickstart on Tue Aug 26 14:19:49 2014.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys
+import os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- 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
+
+call('doxygen')
+
+# -- Function to get output of a command ----------------------------------
+def run_cmd_get_output(cmd):
+    process = Popen(shlex.split(cmd), stdout=PIPE)
+    (output, err) = process.communicate()
+    exit_code = process.wait()
+    if exit_code != 0:
+        raise RuntimeError('command line program has failed')
+    return output
+
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['breathe']
+
+# Breathe extension variables
+breathe_projects = { "esp32-idf": "xml/" }
+breathe_default_project = "esp32-idf"
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'ESP32 Programming Guide'
+copyright = u'2016, Espressif'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# This is supposed to be "the short X.Y version", but it's the only version
+# visible when you open index.html.
+# Display full version to make things less confusing.
+# If needed, nearest tag is returned by 'git describe --abbrev=0'.
+version = run_cmd_get_output('git describe')
+# The full version, including alpha/beta/rc tags.
+release = run_cmd_get_output('git describe')
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'ReadtheDocsTemplatedoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+  ('index', 'ReadtheDocsTemplate.tex', u'Read the Docs Template Documentation',
+   u'Read the Docs', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'readthedocstemplate', u'Read the Docs Template Documentation',
+     [u'Read the Docs'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  ('index', 'ReadtheDocsTemplate', u'Read the Docs Template Documentation',
+   u'Read the Docs', 'ReadtheDocsTemplate', 'One line description of project.',
+   'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False
+
+# -- 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'
+
+if not on_rtd:  # only import and set the theme if we're building docs locally
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+# otherwise, readthedocs.org uses their theme by default, so no need to specify it
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@ -0,0 +1 @@
+.. include:: ../CONTRIBUTING.rst
--- a/docs/contributor-agreement.rst
+++ b/docs/contributor-agreement.rst
@ -1,5 +1,5 @@
 Contributor Agreement
---------------------
+=====================

 Individual Contributor Non-Exclusive License Agreement
 ------------------------------------------------------
--- a/docs/documenting-code.rst
+++ b/docs/documenting-code.rst
@ -0,0 +1,126 @@
+Documenting Code
+================
+
+Introduction
+------------
+
+When documenting code for this repository, please follow `Doxygen style <http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html#specialblock>`_. You are doing it by inserting special commands, for instance ``@param``, into standard comments blocks like for example ``/* @param ratio this is oxygen to air ratio */``. 
+
+Doxygen is phrasing the code, extracting the commands together with subsequent text, and building documentation out of it.
+
+Typical comment block, that contains documentation of a function, looks like below.
+
+.. image:: _static/doc-code-documentation-inline.png
+   :align: center
+   :alt: Sample inline code documentation
+ 
+Doxygen supports couple of formatting styles. It also gives you great flexibility on level of details to include in documentation. To get the taste of available features please check data reach and very well organized `Doxygen Manual <http://www.stack.nl/~dimitri/doxygen/manual/index.html>`_.
+
+Why we need it?
+---------------
+
+The purpose of this description is to provide quick summary on documentation style used in `espressif/esp-idf <https://github.com/espressif/esp-idf>`_ repository. 
+
+The ultimate goal is to ensure that all the code is consistently documented, so we can use tools like `Sphinx <http://www.sphinx-doc.org/>`_ and `Breathe <https://breathe.readthedocs.io/>`_ to aid preparation and automatic updates of API documentation when the code changes. The above piece of code renders in Sphinx like below:
+
+.. image:: _static/doc-code-documentation-rendered.png
+   :align: center
+   :alt: Sample inline code after rendering
+
+ 
+Go for it!
+----------
+
+When writing code for this repository, please follow guidelines below.
+
+  1. Document all building blocks of code: functions, structs, typedefs, enums, macros, etc. Provide enough information on purpose, functionality and limitations of documented items, as you would like to see them documented when reading the code by others.
+
+  2. Documentation of function should describe what this function does. If it accepts input parameters and returns some value, all of them should be explained.
+
+  3. Do not add a data type before parameter or any other characters besides spaces. All spaces and line breaks are compressed into a single space. If you like to break a line, then break it twice.
+
+    .. image:: _static/doc-code-function.png
+       :align: center
+       :alt: Sample function documented inline and after rendering
+
+  4. If function has void input or does not return any value, then skip ``@param`` or ``@return``
+
+    .. image:: _static/doc-code-void-function.png
+       :align: center
+       :alt: Sample void function documented inline and after rendering
+ 
+  5. When documenting members of a ``struct``, ``typedef`` or ``enum``, place specific comment like below after each member.
+
+    .. image:: _static/doc-code-member.png
+       :align: center
+       :alt: Sample of member documentation inline and after rendering
+ 
+  6. To provide well formatted lists, break the line after command (like ``@return`` in example below).
+
+    ::
+
+      ...
+      *
+      * @return
+      *    - ESP_OK if erase operation was successful
+      *    - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
+      *    - ESP_ERR_NVS_READ_ONLY if handle was opened as read only
+      *    - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist
+      *    - other error codes from the underlying storage driver
+      *
+      ...
+ 
+
+  7. Overview of functionality of documented header file, or group of files that make a library, should be placed in separate ``README.rst`` file. 
+
+Go one extra mile
+-----------------
+
+There are couple of tips how you can make your documentation even better and more useful to the reader.
+
+Add code snippets to illustrate implementation. To do so, enclose the snippet using ``@code{c}`` and ``@endcode`` commands.
+
+::
+
+   ...
+   *
+   * @code{c}
+   * // Example of using nvs_get_i32:
+   * int32_t max_buffer_size = 4096; // default value
+   * esp_err_t err = nvs_get_i32(my_handle, "max_buffer_size", &max_buffer_size);
+   * assert(err == ESP_OK || err == ESP_ERR_NVS_NOT_FOUND);
+   * // if ESP_ERR_NVS_NOT_FOUND was returned, max_buffer_size will still
+   * // have its default value.
+   * @endcode
+   *
+   ...
+
+To highlight some information use command ``@attention`` or ``@note``. Example below also shows how to use a numbered list.
+
+::
+
+   ...
+   *
+   * @attention
+   *     1. This API only impact WIFI_MODE_STA or WIFI_MODE_APSTA mode
+   *     2. If the ESP32 is connected to an AP, call esp_wifi_disconnect to disconnect.
+   *
+   ...
+
+
+Use markdown to make your documentation even more readable. With markdown you can add headers, links, tables and more.
+
+::
+
+   ...
+   *
+   * [ESP32 Technical Reference](http://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf)
+   *
+   ...
+
+Wrap up
+-------
+
+We love good code that is doing cool things. 
+We love it even better, if it is well documented, so we can quickly make it run and also do the cool things.
+
--- a/docs/eclipse-setup.rst
+++ b/docs/eclipse-setup.rst
@ -1,3 +1,6 @@
+Build and Flash with Eclipse IDE
+********************************
+
 Installing Eclipse IDE
 ======================

--- a/docs/index.rst
+++ b/docs/index.rst
@ -0,0 +1,78 @@
+ESP32 Programming Guide
+=======================
+
+.. caution::
+
+   Until ESP-IDF release 1.0, this documentation is a draft. It is incomplete and may have mistakes. Please mind your step!
+
+
+Contents:
+
+.. toctree::
+   :caption: Setup Toolchain
+   :maxdepth: 1
+
+   Windows <windows-setup>
+   Linux <linux-setup>
+   Mac OS <macos-setup>
+
+.. Configure - TBA
+
+.. Connect - TBA
+
+.. toctree::
+   :caption: Build and Flash
+   :maxdepth: 1
+
+   Make <make-project>
+   Eclipse IDE <eclipse-setup>
+
+.. toctree::
+   :caption: What Else?
+   :maxdepth: 1
+   
+   partition-tables
+   build_system
+   openocd
+
+.. toctree::
+   :caption: API Reference
+   :maxdepth: 1
+
+   Wi-Fi <api/esp_wifi>
+   Bluetooth <api/bt>
+   GPIO <api/gpio>
+   Logging <api/log>
+   Non-volatile storage <api/nvs>
+   Virtual filesystem <api/vfs>
+   Template <api/template>
+
+.. toctree::
+   :caption: Technical Reference
+
+   Technical Reference <http://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>
+
+.. Resources - TBA
+   
+.. toctree::
+   :caption: Contribute
+   :maxdepth: 1
+
+   contributing
+   documenting-code
+   contributor-agreement
+
+.. toctree::
+   :caption: Legal
+   :maxdepth: 1
+
+   COPYRIGHT
+
+.. About - TBA
+
+ 
+Indices
+=======
+
+* :ref:`genindex`
+* :ref:`search`
--- a/docs/linux-setup.rst
+++ b/docs/linux-setup.rst
@ -1,3 +1,6 @@
+Set up of Toolchain for Linux
+*****************************
+
 Step 0: Prerequisites
 =====================

--- a/docs/macos-setup.rst
+++ b/docs/macos-setup.rst
@ -1,3 +1,6 @@
+Set up of Toolchain for Mac OS
+******************************
+
 Step 0: Prerequisites
 =====================

--- a/docs/make-project.rst
+++ b/docs/make-project.rst
@ -0,0 +1,63 @@
+Build and Flash with Make
+=========================
+
+Finding a project
+-----------------
+
+As well as the `esp-idf-template <https://github.com/espressif/esp-idf-template>`_ project mentioned in the setup guide, esp-idf comes with some example projects on github in the `examples <https://github.com/espressif/esp-idf/tree/master/examples>`_ directory.
+
+Once you've found the project you want to work with, change to its directory and you can configure and build it:
+
+Configuring your project
+------------------------
+
+`make menuconfig`
+
+Compiling your project
+----------------------
+
+`make all`
+
+... will compile app, bootloader and generate a partition table based on the config.
+
+Flashing your project
+---------------------
+
+When `make all` finishes, it will print a command line to use esptool.py to flash the chip. However you can also do this from make by running:
+
+`make flash`
+
+This will flash the entire project (app, bootloader and partition table) to a new chip. The settings for serial port flashing can be configured with `make menuconfig`.
+
+You don't need to run `make all` before running `make flash`, `make flash` will automatically rebuild anything which needs it.
+
+Compiling & Flashing Just the App
+---------------------------------
+
+After the initial flash, you may just want to build and flash just your app, not the bootloader and partition table:
+
+* `make app` - build just the app.
+* `make app-flash` - flash just the app.
+
+`make app-flash` will automatically rebuild the app if it needs it.
+
+(There's no downside to reflashing the bootloader and partition table each time, if they haven't changed.)
+
+The Partition Table
+-------------------
+
+Once you've compiled your project, the "build" directory will contain a binary file with a name like "my_app.bin". This is an ESP32 image binary that can be loaded by the bootloader.
+
+A single ESP32's flash can contain multiple apps, as well as many different kinds of data (calibration data, filesystems, parameter storage, etc). For this reason a partition table is flashed to offset 0x4000 in the flash.
+
+Each entry in the partition table has a name (label), type (app, data, or something else), subtype and the offset in flash where the partition is loaded.
+
+The simplest way to use the partition table is to `make menuconfig` and choose one of the simple predefined partition tables:
+
+* "Single factory app, no OTA"
+* "Factory app, two OTA definitions"
+
+In both cases the factory app is flashed at offset 0x10000. If you `make partition_table` then it will print a summary of the partition table.
+
+For more details about :doc:`partition tables <partition-tables>` and how to create custom variations, view the :doc:`documentation <partition-tables>`.
+
--- a/docs/openocd.rst
+++ b/docs/openocd.rst
@ -1,3 +1,6 @@
+Debugging
+=========
+
 OpenOCD setup for ESP32
 -----------------------

--- a/docs/partition-tables.rst
+++ b/docs/partition-tables.rst
@ -1,5 +1,8 @@
 Partition Tables
----------------
+================
+
+Overview
+--------

 A single ESP32's flash can contain multiple apps, as well as many different kinds of data (calibration data, filesystems, parameter storage, etc). For this reason a partition table is flashed to offset 0x4000 in the flash.

--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@ -0,0 +1,6 @@
+# This is a list of python packages used to generate documentation. This file is used with pip:
+# pip install requirements.txt
+#
+sphinx
+sphinx-rtd-theme
+breathe
--- a/docs/windows-setup.rst
+++ b/docs/windows-setup.rst
@ -1,5 +1,8 @@
-Step 1: Toolchain for Windows: Quick Steps
-==================================
+Set up of Toolchain for Windows
+*******************************
+
+Step 1: Quick Steps
+===================

 Windows doesn't have a built-in "make" environment, so as well as installing the toolchain you will need a GNU-compatible environment. We use the MSYS2_ environment to provide.
 You don't need to use this environment all the time (you can use Eclipse_ or some other front-end), but it runs behind the scenes.