Merge branch 'feature/categorize_examples_doc_new' into 'master'

Organize examples and API documentation



Organize / categorize growing number of code examples and API documentation,  ref. https://gitlab.espressif.cn:6688/idf/esp-idf/issues/10



This merge request is intended to replace most of https://gitlab.espressif.cn:6688/idf/esp-idf/merge_requests/421. The rest of changes submitted in https://gitlab.espressif.cn:6688/idf/esp-idf/merge_requests/421 will follow.



1. Moved examples to category folders, removed numbers from example names

2. Modified `buid_examples.sh` script to handle new locations of examples

3. Moved api-name.rst files to category folders

4. Updated documentation TOC (`docs/index.rst`)

5. Updated links to examples in API documentation





See merge request !430

docs/api/controller_vhci.rst → docs/api/bluetooth/controller_vhci.rst

@@ -11,13 +11,13 @@ 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:
 
-`05_ble_adv <https://github.com/espressif/esp-idf/blob/master/examples/05_ble_adv/main/app_bt.c>`_ 
+`bluetooth/ble_adv <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/ble_adv/main/app_bt.c>`_ 
 
   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
+.. _Instructions: ../template.html
 
 API Reference
 -------------

docs/api/esp_blufi.rst → docs/api/bluetooth/esp_blufi.rst

@@ -13,7 +13,7 @@ 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:
 
-`12_blufi <https://github.com/espressif/esp-idf/blob/master/examples/12_blufi/main/>`_ 
+`bluetooth/blufi <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/blufi/main/>`_ 
 
 This is a BLUFI demo. This demo can set ESP32's wifi to softap/station/softap&station mode and config wifi connections.
 

docs/api/esp_bt_defs.rst → docs/api/bluetooth/esp_bt_defs.rst

@@ -11,7 +11,7 @@ Application Example
 
 `Instructions`_
 
-.. _Instructions: template.html
+.. _Instructions: ../template.html
 
 
 API Reference

docs/api/esp_bt_device.rst → docs/api/bluetooth/esp_bt_device.rst

@@ -13,7 +13,7 @@ Application Example
 
 `Instructions`_
 
-.. _Instructions: template.html
+.. _Instructions: ../template.html
 
 
 API Reference

docs/api/esp_bt_main.rst → docs/api/bluetooth/esp_bt_main.rst

@@ -11,7 +11,7 @@ Application Example
 
 `Instructions`_
 
-.. _Instructions: template.html
+.. _Instructions: ../template.html
 
 
 API Reference

docs/api/esp_gap_ble.rst → docs/api/bluetooth/esp_gap_ble.rst

@@ -11,14 +11,14 @@ 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/14_gatt_server/main/gatts_demo.c>`_ 
-`15_gattc_demo <https://github.com/espressif/esp-idf/blob/master/examples/15_gatt_client/main/gattc_demo.c>`_ 
+`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.
 
 `Instructions`_
 
-.. _Instructions: template.html
+.. _Instructions: ../template.html
 
 
 API Reference

docs/api/esp_gatt_defs.rst → docs/api/bluetooth/esp_gatt_defs.rst

@@ -11,7 +11,7 @@ Application Example
 
 `Instructions`_
 
-.. _Instructions: template.html
+.. _Instructions: ../template.html
 
 
 API Reference

docs/api/esp_gattc.rst → docs/api/bluetooth/esp_gattc.rst

@@ -11,13 +11,13 @@ 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/15_gatt_client/main/gattc_demo.c>`_ 
+`15_gattc_demo <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/gatt_client/main/gattc_demo.c>`_ 
 
 This is a gatt client demo. This demo can scan devices, connect to the gatt server and discover the service.
 
 `Instructions`_
 
-.. _Instructions: template.html
+.. _Instructions: ../template.html
 
 
 API Reference

docs/api/esp_gatts.rst → docs/api/bluetooth/esp_gatts.rst

@@ -11,13 +11,13 @@ 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/14_gatt_server/main/gatts_demo.c>`_ 
+`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.
 
 `Instructions`_
 
-.. _Instructions: template.html
+.. _Instructions: ../template.html
 
 
 API Reference

docs/api/bt.rst → docs/api/bluetooth/index.rst

@@ -1,9 +1,10 @@
-Bluetooth
-=========
+Bluetooth API
+*************
 
 .. toctree::
-   :caption: Bluetooth APIs
+   :maxdepth: 2
 
    Bluetooth Controller && VHCI <controller_vhci>
    Bluetooth Common <bt_common>
    Bluetooth LE <bt_le>
+

docs/api/esp_eth.rst → docs/api/ethernet/esp_eth.rst

@@ -4,7 +4,7 @@ ETHERNET
 Application Example
 -------------------
 
-ethernet example: `examples/17_ethernet <https://github.com/espressif/esp-idf/tree/master/examples/17_ethernet>`_.
+ethernet example: `examples/ethernet/ethernet <https://github.com/espressif/esp-idf/tree/master/examples/ethernet/ethernet>`_.
 
 API Reference
 -------------

docs/api/ethernet/index.rst

@@ -0,0 +1,8 @@
+Ethernet API
+************
+
+.. toctree::
+   :maxdepth: 1
+
+   Ethernet <esp_eth>
+

docs/api/gpio.rst → docs/api/peripherals/gpio.rst

@@ -10,7 +10,7 @@ Note that GPIO6-11 are usually used for SPI flash. GPIO34-39 can only be set as
 Application Example
 -------------------
 
-GPIO output and input interrupt example: `examples/21_gpio <https://github.com/espressif/esp-idf/tree/master/examples/21_gpio>`_.
+GPIO output and input interrupt example: `examples/peripherals/gpio <https://github.com/espressif/esp-idf/tree/master/examples/peripherals/gpio>`_.
 
 API Reference
 -------------

docs/api/i2c.rst → docs/api/peripherals/i2c.rst

@@ -9,7 +9,7 @@ ESP32 has two I2C controllers which can be set as master mode or slave mode.
 Application Example
 -------------------
 
-I2C master and slave example: `examples/18_i2c <https://github.com/espressif/esp-idf/tree/master/examples/18_i2c>`_.
+I2C master and slave example: `examples/peripherals/i2c <https://github.com/espressif/esp-idf/tree/master/examples/peripherals/i2c>`_.
 
 API Reference
 -------------

docs/api/peripherals/index.rst

@@ -0,0 +1,16 @@
+Peripherals API
+***************
+
+.. toctree::
+   :maxdepth: 1
+
+   GPIO <gpio>
+   UART <uart>
+   I2C <i2c>
+   SPI Master <spi_master>
+   Timer <timer>
+   Pulse Counter <pcnt>
+   Sigma-delta Modulation <sigmadelta>
+   LED Control <ledc>
+   Remote Control <rmt>
+

docs/api/ledc.rst → docs/api/peripherals/ledc.rst

@@ -12,7 +12,7 @@ decrease the duty cycle gradually, allowing for fades without any processor inte
 Application Example
 -------------------
 
-LEDC change duty cycle and fading control example: `examples/29_ledc <https://github.com/espressif/esp-idf/tree/master/examples/29_ledc>`_.
+LEDC change duty cycle and fading control example: `examples/peripherals/ledc <https://github.com/espressif/esp-idf/tree/master/examples/peripherals/ledc>`_.
 
 API Reference
 -------------

docs/api/pcnt.rst → docs/api/peripherals/pcnt.rst

@@ -9,7 +9,7 @@ The PCNT (Pulse Counter) module is designed to count the number of rising and/or
 Application Example
 -------------------
 
-Pulse counter with control signal and event interrupt example: `examples/16_pcnt <https://github.com/espressif/esp-idf/tree/master/examples/16_pcnt>`_.
+Pulse counter with control signal and event interrupt example: `examples/peripherals/pcnt <https://github.com/espressif/esp-idf/tree/master/examples/peripherals/pcnt>`_.
 
 API Reference
 -------------

docs/api/rmt.rst → docs/api/peripherals/rmt.rst

@@ -9,7 +9,7 @@ The RMT (Remote Control) module driver can be used to send and receive infrared
 Application Example
 -------------------
 
-NEC remote control TX and RX example: `examples/11_rmt_nec_tx_rx <https://github.com/espressif/esp-idf/tree/master/examples/11_rmt_nec_tx_rx>`_.
+NEC remote control TX and RX example: `examples/peripherals/rmt_nec_tx_rx <https://github.com/espressif/esp-idf/tree/master/examples/peripherals/rmt_nec_tx_rx>`_.
 
 API Reference
 -------------

docs/api/timer.rst → docs/api/peripherals/timer.rst

@@ -12,7 +12,7 @@ They are all 64-bit generic timers based on 16-bit prescalers and 64-bit auto-re
 Application Example
 -------------------
 
-64-bit hardware timer example: `examples/13_timer_group <https://github.com/espressif/esp-idf/tree/master/examples/13_timer_group>`_.
+64-bit hardware timer example: `examples/peripherals/timer_group <https://github.com/espressif/esp-idf/tree/master/examples/peripherals/timer_group>`_.
 
 API Reference
 -------------

docs/api/uart.rst → docs/api/peripherals/uart.rst

@@ -16,7 +16,7 @@ API Reference
 
 `Instructions`_
 
-.. _Instructions: template.html
+.. _Instructions: ../template.html
 
 Header Files
 ^^^^^^^^^^^^

docs/api/protocols/index.rst

@@ -0,0 +1,8 @@
+Protocols API
+*************
+
+.. toctree::
+   :maxdepth: 1
+
+   mDNS <mdns>
+

docs/api/mdns.rst → docs/api/protocols/mdns.rst

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

docs/api/storage/index.rst

@@ -0,0 +1,12 @@
+Storage API
+***********
+
+.. toctree::
+   :maxdepth: 1
+
+   SPI Flash and Partition APIs <spi_flash>
+   SD/MMC <sdmmc>
+   Non-Volatile Storage <nvs_flash>
+   Virtual Filesystem <vfs>
+   FAT Filesystem <fatfs>
+

docs/api/nvs_flash.rst → docs/api/storage/nvs_flash.rst

@@ -1,11 +1,11 @@
-.. include:: ../../components/nvs_flash/README.rst
+.. include:: ../../../components/nvs_flash/README.rst
 
 Application Example
 -------------------
 
 Two examples are provided in ESP-IDF examples directory:
 
-`07_nvs_rw_value <https://github.com/espressif/esp-idf/blob/master/examples/07_nvs_rw_value/main/nvs_rw_value.c>`_
+`storage/nvs_rw_value <https://github.com/espressif/esp-idf/blob/master/examples/storage/nvs_rw_value/main/nvs_rw_value.c>`_
 
   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.
 
-`08_nvs_rw_blob <https://github.com/espressif/esp-idf/blob/master/examples/08_nvs_rw_blob/main/nvs_rw_blob.c>`_
+`storage/nvs_rw_blob <https://github.com/espressif/esp-idf/blob/master/examples/storage/nvs_rw_blob/main/nvs_rw_blob.c>`_
 
   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/sdmmc.rst → docs/api/storage/sdmmc.rst

@@ -15,7 +15,7 @@ Protocol layer works with the host via ``sdmmc_host_t`` structure. This structur
 Application Example
 -------------------
 
-An example which combines SDMMC driver with FATFS library is provided in ``examples/27_sd_card`` directory. This example initializes the card, writes and reads data from it using POSIX and C library APIs. See README.md file in the example directory for more information.
+An example which combines SDMMC driver with FATFS library is provided in ``examples/storage/sd_card`` directory. This example initializes the card, writes and reads data from it using POSIX and C library APIs. See README.md file in the example directory for more information.
 
 
 Protocol layer APIs

docs/api/spi_flash.rst → docs/api/storage/spi_flash.rst

@@ -1,11 +1,11 @@
-.. include:: ../../components/spi_flash/README.rst
+.. include:: ../../../components/spi_flash/README.rst
 
 Application Example
 -------------------
 
 `Instructions`_
 
-.. _Instructions: template.html
+.. _Instructions: ../template.html
 
 API Reference
 -------------

docs/api/vfs.rst → docs/api/storage/vfs.rst

@@ -1,9 +1,11 @@
-.. include:: ../../components/vfs/README.rst
+.. include:: ../../../components/vfs/README.rst
 
 Application Example
 -------------------
 
-`Instructions <http://esp-idf.readthedocs.io/en/latest/api/template.html>`_
+`Instructions`_
+
+.. _Instructions: ../template.html
 
 API Reference
 -------------

docs/api/system/index.rst

@@ -0,0 +1,13 @@
+System API
+**********
+
+.. toctree::
+   :maxdepth: 1
+
+   Memory Allocation <mem_alloc>
+   Interrupt Allocation <intr_alloc>
+   Watchdogs <wdts>
+   OTA <ota>
+   Deep Sleep <deep_sleep>
+   Logging <log>
+

docs/api/log.rst → docs/api/system/log.rst

@@ -1,17 +1,15 @@
-.. include:: ../../components/log/README.rst
+.. include:: ../../../components/log/README.rst
 
 Application Example
 -------------------
 
 `Instructions`_
 
+.. _Instructions: ../template.html
+
 API Reference
 -------------
 
-`Instructions`_
-
-.. _Instructions: template.html
-
 Header Files
 ^^^^^^^^^^^^
 

docs/api/ulp.rst

@@ -1 +0,0 @@
-.. include:: ../../components/ulp/README.rst

docs/api/esp_wifi.rst → docs/api/wifi/esp_wifi.rst

@@ -16,7 +16,7 @@ API Reference
 
 `Instructions`_
 
-.. _Instructions: template.html
+.. _Instructions: ../template.html
 
 Header Files
 ^^^^^^^^^^^^

docs/api/wifi/index.rst

@@ -0,0 +1,8 @@
+Wi-Fi API
+*********
+
+.. toctree::
+   :maxdepth: 1
+
+   Wi-Fi <esp_wifi>
+   Smart Config <esp_smartconfig>

docs/build_system.rst

@@ -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/04_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 - the certificate file contents are loaded from the text .pem file at compile time.
 
 
 Fully Overriding The Component Makefile

docs/index.rst

@@ -26,118 +26,46 @@ Contents:
 .. toctree::
    :caption: What Else?
    :maxdepth: 1
-   
+
    General Notes <general-notes>
-   partition-tables
-   build_system
-   openocd
-   core_dump
-   Flash encryption <security/flash-encryption>
+   Build System <build_system>
+   Debugging <openocd>
+   ESP32 Core Dump <core_dump>
+   Partition Tables <partition-tables>
+   Flash Encryption <security/flash-encryption>
    Secure Boot <security/secure-boot>
-   ULP coprocessor <api/ulp.rst>
-
-.. API Reference
-   ..
-   Table of Contents Outline
-   ..
-   1. System - TBA
-     1.1. Fundamentals of multiprocessor programming with FreeRTOS - TBA
-     1.2. Application startup flow - TBA
-     1.3. Flash encryption and secure boot: how they work and APIs
-     1.4. Lower Power Coprocessor - TBA
-     1.5. Watchdogs <api/wdts>
-     1.6. Memory allocation <api/mem_alloc>
-     1.7. ...
-   2. Memory - TBA
-     2.1. Memory layout of the application (IRAM/IROM, limitations of each) - TBA
-     2.2. Flash layout and partitions - TBA
-     2.3. Flash access APIs - TBA
-     2.4. Partition APIs - TBA
-     2.5. OTA mechanism (app partitions, OTA partition) and APIs - TBA
-     2.6. ... 
-   3. Wi-Fi
-   4. Bluetooth
-     4.1. BT Classic - TBA
-     4.2. BLE
-   5. Ethernet - TBA
-   6. Interfaces
-     6.1. GPIO
-     6.2. ADC - TBA
-     6.3. DAC - TBA
-     6.4. UART
-     6.5. I2C - TBA
-     6.6. I2S - TBA
-     6.7. SPI - <api/spi_master>
-     6.8. CAN - TBA
-     6.9. SD Controller - TBA
-     6.10. Infrared - TBA
-     6.11. Pulse Counter - TBA
-     6.12. PWM - TBA
-     6.13. LED PWM
-     6.14. ...
-   7. Sensors - TBA
-     7.1. Hall Sensor - TBA
-     7.2. Temperature Sensor - TBA
-     7.3. Touch Sensor - TBA
-   8. Protocols - TBA
-   9. Components
-     9.1. Logging
-     9.2  Non-Volatile Storage
-     9.3  Virtual Filesystem
-     9.3. Http sever - TBA
-   10. Applications - TBA
-   ..
-   API Dcoumentation Teamplate
-   ..
+   Deep Sleep Wake Stubs <deep-sleep-stub>
+   ULP Coprocessor <ulp>
 
 .. toctree::
    :caption: API Reference
-   :maxdepth: 1
+   :maxdepth: 2
 
-   Wi-Fi <api/esp_wifi>
-   Smart Config <api/esp_smartconfig>
-   Bluetooth <api/bt>
-   Watchdogs <api/wdts>
-   OTA <api/ota>
-   GPIO <api/gpio>
-   UART <api/uart>
-   LED Control <api/ledc>
-   Remote Control <api/rmt>
-   Timer <api/timer>
-   I2C <api/i2c>
-   Pulse Counter <api/pcnt>
-   Sigma-delta Modulation <api/sigmadelta>
-   SD/MMC <api/sdmmc>
-   SPI Flash and Partition APIs <api/spi_flash>
-   SPI Master API <api/spi_master>
-   Logging <api/log>
-   Non-Volatile Storage <api/nvs_flash>
-   Virtual Filesystem <api/vfs>
-   FAT Filesystem <api/fatfs>
-   Ethernet <api/esp_eth>
-   Interrupt Allocation <api/intr_alloc>
-   Memory Allocation <api/mem_alloc>
-   Deep Sleep <api/deep_sleep>
-   deep-sleep-stub
-
-   mDNS <api/mdns>
-   Template <api/template>
+   Wi-Fi <api/wifi/index>
+   Bluetooth <api/bluetooth/index>
+   Ethernet <api/ethernet/index>
+   Peripherals <api/peripherals/index>
+   System <api/system/index>
+   Storage <api/storage/index>
+   Protocols <api/protocols/index>
 
 .. toctree::
-   :caption: Technical Reference
-
-   Technical Reference <http://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>
+   :caption: Hardware Reference
 
-.. Resources - TBA
+   Technical Reference Manual <http://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>
+   Pin List and Functions <http://espressif.com/sites/default/files/documentation/esp32_chip_pin_list_en.pdf>
+   Chip Pinout <http://espressif.com/sites/default/files/documentation/esp32_pinout_v1_0.pdf>
+   Silicon Errata <http://espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf>
    
 .. toctree::
    :caption: Contribute
    :maxdepth: 1
 
-   contributing
+   Contributions Guide <contributing>
    Style Guide <style-guide>
-   documenting-code
-   contributor-agreement
+   Documenting Code <documenting-code>
+   API Template <api/template>
+   Contributor Agreement <contributor-agreement>
 
 .. toctree::
    :caption: Legal
@@ -147,8 +75,7 @@ Contents:
 
  
 Indices
--------
+=======
 
 * :ref:`genindex`
-* :ref:`search`
 

docs/ulp.rst

@@ -0,0 +1 @@
+.. include:: ../components/ulp/README.rst