Merge branch 'bugfix/docs_cleanup' into 'master'

Organize examples and API documentation - supplement to !430



This supplement to !430, both intended to replace bulky  !421.



1. Fixed broken links

2. Added links to available examples in API documentation, where missing

3. Updated links to point directly to example folder (to show README.md with example description)

4. Added README.md in docs folder info to point reader to ReadTheDocs instead of doc sources, ref. https://github.com/espressif/esp-idf/issues/243

5. Fixed some typo errors / Sphinx warnings

6. Fixed memory leak in example, ref. https://github.com/espressif/esp-idf/issues/209





See merge request !440

docs/README.md

@@ -0,0 +1,11 @@
+# Documentation Source Folder
+
+This folder contains source files of [ESP-IDF documentation](http://esp-idf.readthedocs.io/).
+
+The sources do not render well in GitHub and some information is not visible at all.
+
+Use actual documentation generated instantly on each commit:
+
+* Main server: http://esp-idf.readthedocs.io/ or http://esp-idf.rtfd.io/
+* Mirror: https://dl.espressif.com/doc/esp-idf/latest/
+

docs/api/bluetooth/controller_vhci.rst

@@ -6,19 +6,17 @@ Overview
 
 `Instructions`_
 
+.. _Instructions: ../template.html
+
 Application Example
 -------------------
 
-Check `/examples <https://github.com/espressif/esp-idf/tree/master/examples>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf/>`_ repository, that contains the following example:
+Check `/examples/bluetooth <https://github.com/espressif/esp-idf/tree/master/examples/bluetooth>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf/>`_ repository, that contains the following example:
 
-`bluetooth/ble_adv <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/ble_adv/main/app_bt.c>`_ 
+`ble_adv <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/ble_adv>`_ 
 
   This is a BLE advertising demo with virtual HCI interface. Send Reset/ADV_PARAM/ADV_DATA/ADV_ENABLE HCI command for BLE advertising.
 
-`Instructions`_
-
-.. _Instructions: ../template.html
-
 API Reference
 -------------
 

docs/api/bluetooth/esp_blufi.rst

@@ -11,11 +11,11 @@ Use should concern these things:
 Application Example
 -------------------
 
-Check `/examples <https://github.com/espressif/esp-idf/tree/master/examples>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf/>`_ repository, that contains the following example:
+Check `/examples/bluetooth <https://github.com/espressif/esp-idf/tree/master/examples/bluetooth>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf>`_ repository, that contains the following example:
 
-`bluetooth/blufi <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/blufi/main/>`_ 
+`blufi <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/blufi>`_ 
 
-This is a BLUFI demo. This demo can set ESP32's wifi to softap/station/softap&station mode and config wifi connections.
+  This is a BLUFI demo. This demo can set ESP32's wifi to softap/station/softap&station mode and config wifi connections.
 
 
 API Reference

docs/api/bluetooth/esp_gap_ble.rst

@@ -1,25 +1,21 @@
 GAP API
-========
+=======
 
 Overview
 --------
 
 `Instructions`_
 
+.. _Instructions: ../template.html
+
 Application Example
 -------------------
 
-Check `/examples <https://github.com/espressif/esp-idf/tree/master/examples>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf/>`_ repository, that contains the following example:
-
-`14_gatts_demo <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/gatt_server/main/gatts_demo.c>`_ 
-`15_gattc_demo <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/gatt_client/main/gattc_demo.c>`_ 
-
-The two demos use different gap api, such like advertising, scan, set device name and others.
+Check `/examples/bluetooth <https://github.com/espressif/esp-idf/tree/master/examples/bluetooth>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf>`_ repository, that contains the following examples:
 
-`Instructions`_
-
-.. _Instructions: ../template.html
+`gatt_server <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/gatt_server>`_, `gatt_client <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/gatt_client>`_ 
 
+  The two demos use different gap api, such like advertising, scan, set device name and others.
 
 API Reference
 -------------
@@ -27,7 +23,7 @@ API Reference
 Header Files
 ^^^^^^^^^^^^
 
-  * `bt/bluedroid/api/include/esp_gap_ble_api.h <https://github.com/espressif/esp-idf/blob/master/components/bt/bluedroid/api/include/esp_gap_ble.h>`_
+  * `bt/bluedroid/api/include/esp_gap_ble_api.h <https://github.com/espressif/esp-idf/blob/master/components/bt/bluedroid/api/include/esp_gap_ble_api.h>`_
 
 
 Macros

docs/api/bluetooth/esp_gattc.rst

@@ -6,18 +6,16 @@ Overview
 
 `Instructions`_
 
+.. _Instructions: ../template.html
+
 Application Example
 -------------------
 
-Check `/examples <https://github.com/espressif/esp-idf/tree/master/examples>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf/>`_ repository, that contains the following example:
-
-`15_gattc_demo <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/gatt_client/main/gattc_demo.c>`_ 
+Check `/examples/bluetooth <https://github.com/espressif/esp-idf/tree/master/examples/bluetooth>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf>`_ repository, that contains the following example:
 
-This is a gatt client demo. This demo can scan devices, connect to the gatt server and discover the service.
+`gatt_client <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/gatt_client>`_ 
 
-`Instructions`_
-
-.. _Instructions: ../template.html
+  This is a gatt client demo. This demo can scan devices, connect to the gatt server and discover the service.
 
 
 API Reference

docs/api/bluetooth/esp_gatts.rst

@@ -6,19 +6,16 @@ Overview
 
 `Instructions`_
 
+.. _Instructions: ../template.html
+
 Application Example
 -------------------
 
-Check `/examples <https://github.com/espressif/esp-idf/tree/master/examples>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf/>`_ repository, that contains the following example:
-
-`14_gatts_demo <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/gatt_server/main/gatts_demo.c>`_ 
-
-This is a gatt server demo. Use gatt api to create a gatt server with send advertising. This gatt server can be connected and the service can be discovery.
+Check `/examples/bluetooth <https://github.com/espressif/esp-idf/tree/master/examples/bluetooth>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf>`_ repository, that contains the following example:
 
-`Instructions`_
-
-.. _Instructions: ../template.html
+`gatt_server <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/gatt_server>`_ 
 
+  This is a gatt server demo. Use gatt api to create a gatt server with send advertising. This gatt server can be connected and the service can be discovery.
 
 API Reference
 -------------

docs/api/peripherals/sigmadelta.rst

@@ -10,7 +10,7 @@ This driver configures the channels of the sigma-delta module.
 Application Example
 -------------------
 
-Sigma-delta Modulation example: `examples/14_sigmadelta <https://github.com/espressif/esp-idf/tree/master/examples/14_sigmadelta>`_.
+Sigma-delta Modulation example: `examples/peripherals/sigmadelta <https://github.com/espressif/esp-idf/tree/master/examples/peripherals/sigmadelta>`_.
 
 API Reference
 -------------

docs/api/peripherals/spi_master.rst

@@ -105,13 +105,18 @@ on the transmission. For received data, use ``rx_data`` and set ``SPI_USE_RXDATA
 not touch the ``tx_buffer`` or ``rx_buffer`` members, because they use the same memory locations
 as ``tx_data`` and ``rx_data``.
 
+Application Example
+-------------------
+ 
+Display graphics on the ILI9341-based 320x240 LCD: `examples/peripherals/spi_master <https://github.com/espressif/esp-idf/tree/master/examples/peripherals/spi_master>`_.
+
 API Reference
 -------------
 
 Header Files
 ^^^^^^^^^^^^
 
-  * `drivers/include/drivers/spi_master.h <https://github.com/espressif/esp-idf/blob/master/components/drivers/include/drivers/spi_master.h>`_
+  * `driver/include/driver/spi_master.h <https://github.com/espressif/esp-idf/blob/master/components/driver/include/driver/spi_master.h>`_
 
 Macros
 ^^^^^^

docs/api/peripherals/uart.rst

@@ -6,18 +6,16 @@ Overview
 
 `Instructions`_
 
+.. _Instructions: ../template.html
+
 Application Example
 -------------------
 
-`Instructions`_
+Configure uart settings and install uart driver to read/write using UART0 and UART1 interfaces: `examples/peripherals/uart <https://github.com/espressif/esp-idf/tree/master/examples/peripherals/uart>`_.
 
 API Reference
 -------------
 
-`Instructions`_
-
-.. _Instructions: ../template.html
-
 Header Files
 ^^^^^^^^^^^^
 

docs/api/protocols/mdns.rst

@@ -163,7 +163,7 @@ Example of using the methods above:
 Application Example
 -------------------
 
-mDNS server/scanner example: `examples/protocols/mdsn <https://github.com/espressif/esp-idf/tree/master/examples/protocols/mdsn>`_.
+mDNS server/scanner example: `examples/protocols/mdns <https://github.com/espressif/esp-idf/tree/master/examples/protocols/mdns>`_.
 
 API Reference
 -------------

docs/api/storage/nvs_flash.rst

@@ -3,9 +3,9 @@
 Application Example
 -------------------
 
-Two examples are provided in ESP-IDF examples directory:
+Two examples are provided in ESP-IDF `examples/storage <https://github.com/espressif/esp-idf/tree/master/examples/storage>`_ directory:
 
-`storage/nvs_rw_value <https://github.com/espressif/esp-idf/blob/master/examples/storage/nvs_rw_value/main/nvs_rw_value.c>`_
+`nvs_rw_value <https://github.com/espressif/esp-idf/blob/master/examples/storage/nvs_rw_value>`_
 
   Demonstrates how to read and write a single integer value using NVS.
 
@@ -13,7 +13,7 @@ Two examples are provided in ESP-IDF examples directory:
 
   Example also shows how to check if read / write operation was successful, or certain value is not initialized in NVS. Diagnostic is provided in plain text to help track program flow and capture any issues on the way.
 
-`storage/nvs_rw_blob <https://github.com/espressif/esp-idf/blob/master/examples/storage/nvs_rw_blob/main/nvs_rw_blob.c>`_
+`nvs_rw_blob <https://github.com/espressif/esp-idf/blob/master/examples/storage/nvs_rw_blob>`_
 
   Demonstrates how to read and write a single integer value and a blob (binary large object) using NVS to preserve them between ESP32 module restarts.
 

docs/api/system/deep_sleep.rst

@@ -87,3 +87,8 @@ The following function can be used to enter deep sleep once wakeup sources are c
 
 .. doxygenfunction:: esp_deep_sleep_start
 
+Application Example
+-------------------
+ 
+Implementation of basic functionality of deep sleep is shown in `protocols/sntp <https://github.com/espressif/esp-idf/tree/master/examples/protocols/sntp>`_ example, where ESP module is periodically waken up to retrive time from NTP server.
+

docs/api/system/log.rst

@@ -3,9 +3,11 @@
 Application Example
 -------------------
 
-`Instructions`_
-
-.. _Instructions: ../template.html
+Log library is commonly used by most of esp-idf components and examples. For demonstration of log functionality check `examples <https://github.com/espressif/esp-idf/tree/master/examples>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf>`_ repository, that among others, contains the following examples:
+ 
+* `system/ota <https://github.com/espressif/esp-idf/tree/master/examples/system/ota>`_ 
+* `storage/sd_card <https://github.com/espressif/esp-idf/tree/master/examples/storage/sd_card>`_ 
+* `protocols/https_request <https://github.com/espressif/esp-idf/tree/master/examples/protocols/https_request>`_ 
 
 API Reference
 -------------

docs/api/system/ota.rst

@@ -1,6 +1,11 @@
 OTA
 ===
 
+Application Example
+-------------------
+ 
+Demonstration of OTA (over the air) firmware update workflow: `examples/system/ota <https://github.com/espressif/esp-idf/tree/master/examples/system/ota>`_.
+
 API Reference
 -------------
 

docs/api/wifi/esp_smartconfig.rst

@@ -1,5 +1,5 @@
 Smart Config
-===
+============
 
 API Reference
 -------------

docs/api/wifi/esp_wifi.rst

@@ -6,18 +6,16 @@ Overview
 
 `Instructions`_
 
+.. _Instructions: ../template.html
+
 Application Example
 -------------------
 
-`Instructions`_
+Simple code showing how to connect ESP32 module to an Access Point: `esp-idf-template <https://github.com/espressif/esp-idf-template>`_.
 
 API Reference
 -------------
 
-`Instructions`_
-
-.. _Instructions: ../template.html
-
 Header Files
 ^^^^^^^^^^^^
 

docs/build_system.rst → docs/build-system.rst

@@ -131,7 +131,7 @@ Component Makefiles
 
 Each project contains one or more components, which can either be part of esp-idf or added from other component directories.
 
-A component is any sub-directory that contains a `component.mk` file.[#f1]_.
+A component is any sub-directory that contains a `component.mk` file [#f1]_.
 
 Minimal Component Makefile
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -464,7 +464,7 @@ The file's contents will be added to the .rodata section in flash, and are avail
 
 The names are generated from the full name of the file, as given in COMPONENT_EMBED_FILES. Characters /, ., etc. are replaced with underscores. The _binary prefix in the symbol name is added by objcopy and is the same for both text and binary files.
 
-For an example of using this technique, see examples/protocols/https_request - the certificate file contents are loaded from the text .pem file at compile time.
+For an example of using this technique, see `examples/protocols/https_request <https://github.com/espressif/esp-idf/tree/master/examples/protocols/https_request>`_ - the certificate file contents are loaded from the text .pem file at compile time.
 
 
 Fully Overriding The Component Makefile
@@ -485,7 +485,7 @@ is set then the component can instruct the linker to link other binaries instead
 
 .. _esp-idf-template: https://github.com/espressif/esp-idf-template
 .. _GNU Make Manual: https://www.gnu.org/software/make/manual/make.html
-.. _[_f1]: Actually, some components in esp-idf are "pure configuration" components that don't have a component.mk file, only a Makefile.projbuild and/or Kconfig.projbuild file. However, these components are unusual and most components have a component.mk file.
+.. [#f1] Actually, some components in esp-idf are "pure configuration" components that don't have a component.mk file, only a Makefile.projbuild and/or Kconfig.projbuild file. However, these components are unusual and most components have a component.mk file.
 
 
 Custom sdkconfig defaults

docs/conf.py

@@ -65,8 +65,8 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = u'ESP32 Programming Guide'
-copyright = u'2016, Espressif'
+project = u'ESP-IDF Programming Guide'
+copyright = u'2016 - 2017, 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

docs/index.rst

@@ -28,7 +28,7 @@ Contents:
    :maxdepth: 1
 
    General Notes <general-notes>
-   Build System <build_system>
+   Build System <build-system>
    Debugging <openocd>
    ESP32 Core Dump <core_dump>
    Partition Tables <partition-tables>

docs/security/flash-encryption.rst

@@ -291,11 +291,13 @@ Flash Encryption Algorithm
 - Each 32 byte block is encrypted with a unique key which is derived from this main flash encryption key XORed with the offset of this block in the flash (a "key tweak").
 
 - The specific tweak depends on the setting of ``FLASH_CRYPT_CONFIG`` efuse. This is a 4 bit efuse, where each bit enables XORing of a particular range of the key bits:
+
   - Bit 1, bits 0-66 of the key are XORed.
   - Bit 2, bits 67-131 of the key are XORed.
   - Bit 3, bits 132-194 of the key are XORed.
   - Bit 4, bits 195-256 of the key are XORed.
-It is recommended that ``FLASH_CRYPT_CONFIG`` is always left to set the default value `0xF`, so that all key bits are XORed with the block offset. See `Setting FLASH_CRYPT_CONFIG` for details.
+
+  It is recommended that ``FLASH_CRYPT_CONFIG`` is always left to set the default value `0xF`, so that all key bits are XORed with the block offset. See `Setting FLASH_CRYPT_CONFIG` for details.
 
 - The high 19 bits of the block offset (bit 5 to bit 23) are XORed with the main flash encryption key. This range is chosen for two reasons: the maximum flash size is 16MB (24 bits), and each block is 32 bytes so the least significant 5 bits are always zero.
 

examples/storage/nvs_rw_blob/main/nvs_rw_blob.c

@@ -87,10 +87,10 @@ esp_err_t save_run_time(void)
     required_size += sizeof(uint32_t);
     run_time[required_size / sizeof(uint32_t) - 1] = xTaskGetTickCount() * portTICK_PERIOD_MS;
     err = nvs_set_blob(my_handle, "run_time", run_time, required_size);
-    if (err != ESP_OK) return err;
-
     free(run_time);
 
+    if (err != ESP_OK) return err;
+
     // Commit
     err = nvs_commit(my_handle);
     if (err != ESP_OK) return err;

examples/storage/sd_card/README.md

@@ -32,7 +32,8 @@ N/C           | WP          |
 This example doesn't utilize card detect (CD) and write protect (WP) signals from SD card slot.
 
 ### Note about GPIO2
-GPIO2 pin is used as a bootstrapping pin, and should be low to enter UART download mode. One way to do this is to connect GPIO0 and GPIO2 using a jumper, and then the auto-reset circuit on most development boards will pull GPIO2 low along with GPIO2, when entering download mode.
+
+GPIO2 pin is used as a bootstrapping pin, and should be low to enter UART download mode. One way to do this is to connect GPIO0 and GPIO2 using a jumper, and then the auto-reset circuit on most development boards will pull GPIO2 low along with GPIO0, when entering download mode.
 
 ### Note about GPIO12