docs: Generate Doxygen directives for API documentation

This is to resolve issue reported in https://github.com/espressif/esp-idf/issues/130.

.gitignore

@@ -26,6 +26,7 @@ examples/**/build
 #Doc build artifacts
 docs/_build/
 docs/doxygen-warning-log.txt
+docs/sphinx-warning-log.txt
 docs/xml/
 docs/man/
 

components/driver/include/driver/dac.h

@@ -28,7 +28,7 @@ typedef enum {
     DAC_CHANNEL_MAX,
 } dac_channel_t;
 
-
+/** @cond */
 /**
   * @brief  Set DAC output voltage.
   *
@@ -45,6 +45,7 @@ typedef enum {
   *     - ESP_ERR_INVALID_ARG Parameter error
   */
 esp_err_t dac_out_voltage(dac_channel_t channel, uint8_t dac_value) __attribute__ ((deprecated));
+/** @endcond */
 
 /**
  * @brief Set DAC output voltage.

components/driver/include/driver/gpio.h

@@ -31,7 +31,13 @@ extern "C" {
 
 #define GPIO_SEL_0              (BIT(0))                         /*!< Pin 0 selected */
 #define GPIO_SEL_1              (BIT(1))                         /*!< Pin 1 selected */
-#define GPIO_SEL_2              (BIT(2))                         /*!< Pin 2 selected */
+#define GPIO_SEL_2              (BIT(2))                         /*!< Pin 2 selected 
+                                                                      @note There are more macros
+                                                                      like that up to pin 39,
+                                                                      excluding pins 20, 24 and 28..31.
+                                                                      They are not shown here 
+                                                                      to reduce redundant information. */
+/** @cond */
 #define GPIO_SEL_3              (BIT(3))                         /*!< Pin 3 selected */
 #define GPIO_SEL_4              (BIT(4))                         /*!< Pin 4 selected */
 #define GPIO_SEL_5              (BIT(5))                         /*!< Pin 5 selected */
@@ -114,14 +120,21 @@ extern "C" {
 #define GPIO_MODE_DEF_OD              (BIT2)
 
 #define GPIO_PIN_COUNT              40
+/** @endcond */
+
 extern const uint32_t GPIO_PIN_MUX_REG[GPIO_PIN_COUNT];
-#define GPIO_IS_VALID_GPIO(gpio_num)      ((gpio_num < GPIO_PIN_COUNT && GPIO_PIN_MUX_REG[gpio_num] != 0))   //to decide whether it is a valid GPIO number
-#define GPIO_IS_VALID_OUTPUT_GPIO(gpio_num)      ((GPIO_IS_VALID_GPIO(gpio_num)) && (gpio_num < 34))         //to decide whether it can be a valid GPIO number of output mode
+#define GPIO_IS_VALID_GPIO(gpio_num)      ((gpio_num < GPIO_PIN_COUNT && GPIO_PIN_MUX_REG[gpio_num] != 0))   /*!< Check whether it is a valid GPIO number */
+#define GPIO_IS_VALID_OUTPUT_GPIO(gpio_num)      ((GPIO_IS_VALID_GPIO(gpio_num)) && (gpio_num < 34))         /*!< Check whether it can be a valid GPIO number of output mode */
 
 typedef enum {
     GPIO_NUM_0 = 0,     /*!< GPIO0, input and output */
     GPIO_NUM_1 = 1,     /*!< GPIO1, input and output */
-    GPIO_NUM_2 = 2,     /*!< GPIO2, input and output */
+    GPIO_NUM_2 = 2,     /*!< GPIO2, input and output
+		                     @note There are more enumerations like that
+                             up to GPIO39, excluding GPIO20, GPIO24 and GPIO28..31.
+		                     They are not shown here to reduce redundant information.
+                             @note GPIO34..29 are input mode only. */
+/** @cond */
     GPIO_NUM_3 = 3,     /*!< GPIO3, input and output */
     GPIO_NUM_4 = 4,     /*!< GPIO4, input and output */
     GPIO_NUM_5 = 5,     /*!< GPIO5, input and output */
@@ -157,6 +170,7 @@ typedef enum {
     GPIO_NUM_38 = 38,   /*!< GPIO38, input mode only */
     GPIO_NUM_39 = 39,   /*!< GPIO39, input mode only */
     GPIO_NUM_MAX = 40,
+/** @endcond */    
 } gpio_num_t;
 
 typedef enum {

components/driver/include/driver/spi_common.h

@@ -48,6 +48,8 @@ typedef enum {
  * You can use this structure to specify the GPIO pins of the bus. Normally, the driver will use the
  * GPIO matrix to route the signals. An exception is made when all signals either can be routed through 
  * the IO_MUX or are -1. In that case, the IO_MUX is used, allowing for >40MHz speeds.
+ *
+ * @note Be advised that the slave driver does not use the quadwp/quadhd lines and fields in spi_bus_config_t refering to these lines will be ignored and can thus safely be left uninitialized.
  */
 typedef struct {
     int mosi_io_num;                ///< GPIO pin for Master Out Slave In (=spi_d) signal, or -1 if not used.
@@ -230,4 +232,4 @@ void spicommon_dmaworkaround_transfer_active(int dmachan);
 }
 #endif
 
-#endif
+#endif

components/ethernet/include/eth_phy/phy.h

@@ -20,13 +20,13 @@ extern "C" {
 
 #include "esp_eth.h"
 
-/* Common PHY-management functions.
+/** Common PHY-management functions.
 
    These are not enough to drive any particular Ethernet PHY, but they provide a common configuration structure and
    management functions.
 */
 
-/* Configure fixed pins for RMII data interface.
+/** Configure fixed pins for RMII data interface.
 
    This configures GPIOs 0, 19, 22, 25, 26, 27 for use with RMII
    data interface. These pins cannot be changed, and must be wired to
@@ -38,7 +38,7 @@ extern "C" {
 */
 void phy_rmii_configure_data_interface_pins(void);
 
-/* Configure variable pins for SMI (MDIO) ethernet functions.
+/** Configure variable pins for SMI (MDIO) ethernet functions.
 
    Calling this function along with mii_configure_default_pins() will
    fully configure the GPIOs for the ethernet PHY.
@@ -46,7 +46,7 @@ void phy_rmii_configure_data_interface_pins(void);
 void phy_rmii_smi_configure_pins(uint8_t mdc_gpio, uint8_t mdio_gpio);
 
 
-/* Enable flow control in standard PHY MII register.
+/** Enable flow control in standard PHY MII register.
  */
 void phy_mii_enable_flow_ctrl(void);
 

components/ethernet/include/eth_phy/phy_lan8720.h

@@ -21,26 +21,26 @@ extern "C" {
 #include "phy.h"
 
 
-/* @brief Dump all LAN8720 PHY SMI configuration registers
+/** @brief Dump all LAN8720 PHY SMI configuration registers
  *
  * @note These registers are dumped at 'debug' level, so output
  * may not be visible depending on default log levels.
  */
 void phy_lan8720_dump_registers();
 
-/* @brief Default LAN8720 phy_check_init function.
+/** @brief Default LAN8720 phy_check_init function.
  */
 void phy_lan8720_check_phy_init(void);
 
-/* @brief Default LAN8720 phy_get_speed_mode function.
+/** @brief Default LAN8720 phy_get_speed_mode function.
  */
 eth_speed_mode_t phy_lan8720_get_speed_mode(void);
 
-/* @brief Default LAN8720 phy_get_duplex_mode function.
+/** @brief Default LAN8720 phy_get_duplex_mode function.
  */
 eth_duplex_mode_t phy_lan8720_get_duplex_mode(void);
 
-/* @brief Default LAN8720 phy_power_enable function.
+/** @brief Default LAN8720 phy_power_enable function.
  *
  * @note This function may need to be replaced with a custom function
  * if the PHY has a GPIO to enable power or start a clock.
@@ -49,11 +49,11 @@ eth_duplex_mode_t phy_lan8720_get_duplex_mode(void);
  */
 void phy_lan8720_power_enable(bool);
 
-/* @brief Default LAN8720 phy_init function.
+/** @brief Default LAN8720 phy_init function.
  */
 void phy_lan8720_init(void);
 
-/* @brief Default LAN8720 PHY configuration
+/** @brief Default LAN8720 PHY configuration
  *
  * This configuration is not suitable for use as-is, it will need
  * to be modified for your particular PHY hardware setup.

components/ethernet/include/eth_phy/phy_tlk110.h

@@ -20,26 +20,26 @@ extern "C" {
 
 #include "phy.h"
 
-/* @brief Dump all TLK110 PHY SMI configuration registers
+/** @brief Dump all TLK110 PHY SMI configuration registers
  *
  * @note These registers are dumped at 'debug' level, so output
  * may not be visible depending on default log levels.
  */
 void phy_tlk110_dump_registers();
 
-/* @brief Default TLK110 phy_check_init function.
+/** @brief Default TLK110 phy_check_init function.
  */
 void phy_tlk110_check_phy_init(void);
 
-/* @brief Default TLK110 phy_get_speed_mode function.
+/** @brief Default TLK110 phy_get_speed_mode function.
  */
 eth_speed_mode_t phy_tlk110_get_speed_mode(void);
 
-/* @brief Default TLK110 phy_get_duplex_mode function.
+/** @brief Default TLK110 phy_get_duplex_mode function.
  */
 eth_duplex_mode_t phy_tlk110_get_duplex_mode(void);
 
-/* @brief Default TLK110 phy_power_enable function.
+/** @brief Default TLK110 phy_power_enable function.
  *
  * @note This function may need to be replaced with a custom function
  * if the PHY has a GPIO to enable power or start a clock.
@@ -48,11 +48,11 @@ eth_duplex_mode_t phy_tlk110_get_duplex_mode(void);
  */
 void phy_tlk110_power_enable(bool);
 
-/* @brief Default TLK110 phy_init function.
+/** @brief Default TLK110 phy_init function.
  */
 void phy_tlk110_init(void);
 
-/* @brief Default TLK110 PHY configuration
+/** @brief Default TLK110 PHY configuration
  *
  * This configuration is not suitable for use as-is, it will need
  * to be modified for your particular PHY hardware setup.

components/vfs/README.rst

@@ -13,7 +13,13 @@ For example, one can register a FAT filesystem driver with ``/fat`` prefix, and
 FS registration
 ---------------
 
-To register an FS driver, application needs to define in instance of esp_vfs_t structure and populate it with function pointers to FS APIs::
+
+
+To register an FS driver, application needs to define in instance of esp_vfs_t structure and populate it with function pointers to FS APIs:
+
+.. highlight:: c
+
+::
 
     esp_vfs_t myfs = {
         .fd_offset = 0,
@@ -97,6 +103,8 @@ Lower ``CONFIG_MAX_FD_BITS`` bits are used to store zero-based file descriptor.
 
 When VFS component receives a call from newlib which has a file descriptor, this file descriptor is translated back to the FS-specific file descriptor. First, higher bits of FD are used to identify the FS. Then ``fd_offset`` field of the FS is added to the lower ``CONFIG_MAX_FD_BITS`` bits of the fd, and resulting FD is passed to the FS driver.
 
+.. highlight:: none
+
 ::
 
        FD as seen by newlib                                    FD as seen by FS driver
@@ -132,15 +140,19 @@ Note that while writing to ``stdout`` or ``stderr`` will block until all charact
 Standard streams and FreeRTOS tasks
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-``FILE`` objects for ``stdin``, ``stdout``, and ``stderr`` are shared between all FreeRTOS tasks, but the pointers to these objects are are stored in per-task ``struct _reent``. The following code::
+``FILE`` objects for ``stdin``, ``stdout``, and ``stderr`` are shared between all FreeRTOS tasks, but the pointers to these objects are are stored in per-task ``struct _reent``. The following code:
+
+.. highlight:: c
+
+::
 
     fprintf(stderr, "42\n");
 
-actually is translated to to this (by the preprocessor):
+actually is translated to to this (by the preprocessor)::
 
     fprintf(__getreent()->_stderr, "42\n");
 
-where the ``__getreent()`` function returns a per-task pointer to ``struct _reent`` (:component_file:`newlib/include/sys/reent.h#L370-L417>`). This structure is allocated on the TCB of each task. When a task is initialized, ``_stdin``, ``_stdout`` and ``_stderr`` members of ``struct _reent`` are set to the values of ``_stdin``, ``_stdout`` and ``_stderr`` of ``_GLOBAL_REENT`` (i.e. the structure which is used before FreeRTOS is started).
+where the ``__getreent()`` function returns a per-task pointer to ``struct _reent`` (:component_file:`newlib/include/sys/reent.h#L370-L417`). This structure is allocated on the TCB of each task. When a task is initialized, ``_stdin``, ``_stdout`` and ``_stderr`` members of ``struct _reent`` are set to the values of ``_stdin``, ``_stdout`` and ``_stderr`` of ``_GLOBAL_REENT`` (i.e. the structure which is used before FreeRTOS is started).
 
 Such a design has the following consequences:
 

docs/Doxyfile

@@ -15,51 +15,145 @@
 
 PROJECT_NAME = "ESP32 Programming Guide"
 
-INPUT = ../components/esp32/include/esp_wifi.h \
-	../components/driver/include/driver \
-	../components/bt/include \
-	../components/bt/bluedroid/api/include \
-	../components/nvs_flash/include \
-	../components/log/include \
-	../components/vfs/include \
-	../components/spi_flash/include \
-	../components/esp32/include/esp_int_wdt.h \
-	../components/esp32/include/esp_task_wdt.h \
-	../components/app_update/include/esp_ota_ops.h \
-	../components/ethernet/include/esp_eth.h \
-	../components/ulp/include/esp32/ulp.h \
-	../components/esp32/include/esp_intr_alloc.h \
-	../components/esp32/include/esp_heap_alloc_caps.h \
-	../components/freertos/include/freertos/heap_regions.h \
-	../components/esp32/include/esp_smartconfig.h \
-	../components/esp32/include/esp_deep_sleep.h \
-	../components/sdmmc/include/sdmmc_cmd.h \
-	../components/fatfs/src/esp_vfs_fat.h \
-	../components/fatfs/src/diskio.h \
-	../components/esp32/include/esp_core_dump.h \
-	../components/mdns/include/mdns.h \
-	../components/bootloader_support/include/esp_flash_encrypt.h \
-    ../components/wear_levelling/include/wear_levelling.h
+## The 'INPUT' statement below is used as input by script 'gen-df-input.py'
+## to automatically generate API reference list files heder_file.inc
+## These files are placed in '_inc' directory 
+## and used to include in API reference documentation
+
+INPUT = \
+    ##
+    ## Wi-Fi - API Reference
+    ##
+    ../components/esp32/include/esp_wifi.h \
+    ../components/esp32/include/esp_smartconfig.h \
+    ## Bluetooth - API Reference
+    ## Controller && VHCI
+    ../components/bt/include/bt.h \
+    ## Bluetooth COMMON
+    ## Issue with __attribute__
+    ../components/bt/bluedroid/api/include/esp_bt_defs.h \
+    ../components/bt/bluedroid/api/include/esp_bt_main.h \
+    ../components/bt/bluedroid/api/include/esp_bt_device.h \
+    ## Bluetooth LE
+    ../components/bt/bluedroid/api/include/esp_gap_ble_api.h \
+    ## Issue with __attribute__
+    ../components/bt/bluedroid/api/include/esp_gatt_defs.h \
+    ../components/bt/bluedroid/api/include/esp_gatts_api.h \
+    ../components/bt/bluedroid/api/include/esp_gattc_api.h \
+    ../components/bt/bluedroid/api/include/esp_blufi_api.h \
+    ## Bluetooth Classic
+    ../components/bt/bluedroid/api/include/esp_gap_bt_api.h \
+    ## Issue with __attribute__
+    ../components/bt/bluedroid/api/include/esp_a2dp_api.h \
+    ../components/bt/bluedroid/api/include/esp_avrc_api.h \
+    ##
+    ## Ethernet - API Reference
+    ##
+    ../components/ethernet/include/esp_eth.h \
+    ../components/ethernet/include/eth_phy/phy.h \
+    ../components/ethernet/include/eth_phy/phy_tlk110.h \
+    ../components/ethernet/include/eth_phy/phy_lan8720.h \
+    ##
+    ## Peripherals - API Reference
+    ##
+    ../components/driver/include/driver/adc.h \
+    ../components/driver/include/driver/dac.h \
+    ../components/driver/include/driver/gpio.h \
+    ../components/driver/include/driver/rtc_io.h \
+    ../components/driver/include/driver/i2c.h \
+    ../components/driver/include/driver/i2s.h \
+    ../components/driver/include/driver/ledc.h \
+    ../components/driver/include/driver/mcpwm.h \
+    ../components/driver/include/driver/pcnt.h \
+    ../components/driver/include/driver/rmt.h \
+    ../components/driver/include/driver/sigmadelta.h \
+    ../components/driver/include/driver/spi_common.h \
+    ../components/driver/include/driver/spi_master.h \
+    ../components/driver/include/driver/spi_slave.h \
+    ../components/driver/include/driver/timer.h \
+    ../components/driver/include/driver/uart.h \
+    ##
+    ## Protocols - API Reference
+    ##
+    ../components/mdns/include/mdns.h \
+    ##
+    ## Storage - API Reference
+    ##
+    ## SPI Flash and Partition APIs
+    ../components/spi_flash/include/esp_spi_flash.h \
+    ../components/spi_flash/include/esp_partition.h \
+    ../components/bootloader_support/include/esp_flash_encrypt.h \
+    ## SD/MMC Card Host
+    ## NOTE: for three lines below header_file.inc is not used
+    ../components/sdmmc/include/sdmmc_cmd.h \
+    ../components/driver/include/driver/sdmmc_host.h \
+    ../components/driver/include/driver/sdmmc_types.h \
+    ## Non-Volatile Storage
+    ../components/nvs_flash/include/nvs.h \
+    ../components/nvs_flash/include/nvs_flash.h \
+    ## Virtual Filesystem
+    ../components/vfs/include/esp_vfs.h \
+    ../components/vfs/include/esp_vfs_dev.h \
+    ## FAT Filesystem
+    ## NOTE: for two lines below header_file.inc is not used
+    ../components/fatfs/src/esp_vfs_fat.h \
+    ../components/fatfs/src/diskio.h \
+    ## Wear Levelling
+    ../components/wear_levelling/include/wear_levelling.h \
+    ##
+    ## System - API Reference
+    ##
+    ## Memory Allocation    #
+    ../components/esp32/include/esp_heap_alloc_caps.h \
+    ../components/freertos/include/freertos/heap_regions.h \
+    ## Interrupt Allocation
+    ../components/esp32/include/esp_intr_alloc.h \
+    ## Watchdogs
+    ## NOTE: for two lines below header_file.inc is not used
+    ../components/esp32/include/esp_int_wdt.h \
+    ../components/esp32/include/esp_task_wdt.h \
+    ## Over The Air Updates (OTA)
+    ../components/app_update/include/esp_ota_ops.h \
+    ## Deep Sleep
+    ## NOTE: for line below header_file.inc is not used
+    ../components/esp32/include/esp_deep_sleep.h \
+    ## Logging
+    ../components/log/include/esp_log.h \
+    ## Base MAC address
+    ## NOTE: for line below header_file.inc is not used
+    ../components/esp32/include/esp_system.h \
+    ##
+    ## ULP Coprocessor - API Guides
+    ##
+    ## NOTE: for line below header_file.inc is not used
+    ../components/ulp/include/esp32/ulp.h
 
 
 ## Get warnings for functions that have no documentation for their parameters or return value 
 ##
 WARN_NO_PARAMDOC = YES
 
+## Enable preprocessing and remove __attribute__(...) expressions from the INPUT files
+##
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+PREDEFINED             = __attribute__(x)=
+
 ## Do not complain about not having dot
 ##
 HAVE_DOT = NO
 
 ## Generate XML that is required for Breathe
 ##
-GENERATE_XML = YES
-XML_OUTPUT = xml
+GENERATE_XML    = YES
+XML_OUTPUT      = xml
 
-GENERATE_HTML		= NO
-HAVE_DOT		= NO
-GENERATE_LATEX		= NO
-GENERATE_MAN		= YES
-GENERATE_RTF		= NO
+GENERATE_HTML   = NO
+HAVE_DOT        = NO
+GENERATE_LATEX  = NO
+GENERATE_MAN    = YES
+GENERATE_RTF    = NO
 
 ## Skip distracting progress messages
 ##
@@ -67,3 +161,4 @@ QUIET = YES
 ## Log warnings in a file for further review
 ##
 WARN_LOGFILE = "doxygen-warning-log.txt"
+

docs/Makefile

@@ -15,7 +15,7 @@ endif
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) -w sphinx-warning-log.txt .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
@@ -170,14 +170,14 @@ gh-linkcheck:
 		echo "WARNINIG: Some .rst files contain hardcoded Github links."; \
 		echo "Please check above output and replace links with one of the following:"; \
 		echo "- :idf:\`dir\` - points to directory inside ESP-IDF"; \
-		echo "- :idf_blob:\`file\` - points to file inside ESP-IDF"; \
+		echo "- :idf_file:\`file\` - points to file inside ESP-IDF"; \
 		echo "- :idf_raw:\`file\` - points to raw view of the file inside ESP-IDF"; \
 		echo "- :component:\`dir\` - points to directory inside ESP-IDF components dir"; \
-		echo "- :component_blob:\`file\` - points to file inside ESP-IDF components dir"; \
+		echo "- :component_file:\`file\` - points to file inside ESP-IDF components dir"; \
 		echo "- :component_raw:\`file\` - points to raw view of the file inside ESP-IDF"; \
 		echo "  components dir"; \
 		echo "- :example:\`dir\` - points to directory inside ESP-IDF examples dir"; \
-		echo "- :example_blob:\`file\` - points to file inside ESP-IDF examples dir"; \
+		echo "- :example_file:\`file\` - points to file inside ESP-IDF examples dir"; \
 		echo "- :example_raw:\`file\` - points to raw view of the file inside ESP-IDF"; \
 		echo "  examples dir"; \
 		echo "These link types will point to the correct GitHub version automatically"; \

docs/api-guides/build-system.rst

@@ -508,20 +508,20 @@ To override the name of this file, set the ``SDKCONFIG_DEFAULTS`` environment va
 
 
 Save flash arguments
--------------------------
+--------------------
+
+There're some scenarios that we want to flash the target board without IDF. For this case we want to save the built binaries, esptool.py and esptool write_flash arguments. It's simple to write a script to save binaries and esptool.py. For flash arguments, we can add the following code to application project makefile::
 
-There're some scenarios that we want to flash the target board without IDF. For this case we want to save the built binaries, esptool.py and esptool write_flash arguments. It's simple to write a script to save binaries and esptool.py. For flash arguments, we can add the following code to application project makefile:
-::
     print_flash_cmd:
         echo $(ESPTOOL_WRITE_FLASH_OPTIONS) $(ESPTOOL_ALL_FLASH_ARGS) | sed -e 's:'$(PWD)/build/'::g'
     
 the original ESPTOOL_ALL_FLASH_ARGS are absolute file name. Usually we want to save relative file name so we can move the bin folder to somewhere else. For this case we can use ``sed`` to convert to relative file name, like what we did in the example above.
 
-When running ``make print_flash_cmd``, it will print the flash arguments:
-::
+When running ``make print_flash_cmd``, it will print the flash arguments::
+
     --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin
 
-Then use flash arguments as the arguemnts for esptool write_flash arguments:
-::
+Then use flash arguments as the arguemnts for esptool write_flash arguments::
+
     python esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin
 

docs/api-reference/bluetooth/controller_vhci.rst

@@ -11,49 +11,11 @@ Overview
 Application Example
 -------------------
 
-Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following example:
+Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following application:
 
-:example:`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.
+* This is a BLE advertising demo with virtual HCI interface. Send Reset/ADV_PARAM/ADV_DATA/ADV_ENABLE HCI command for BLE advertising - :example:`bluetooth/ble_adv`.
 
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
-
-  * :component_file:`bt/include/bt.h`
-
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-.. doxygentypedef:: esp_vhci_host_callback_t
-
-Enumerations
-^^^^^^^^^^^^
-
-.. doxygenenum:: esp_bt_mode_t
-
-Structures
-^^^^^^^^^^
-
-.. doxygenstruct:: esp_bt_controller_config_t
-    :members:
-
-.. doxygenstruct:: esp_vhci_host_callback
-    :members:
-
-
-Functions
-^^^^^^^^^
-
-.. doxygenfunction:: esp_bt_controller_init
-.. doxygenfunction:: esp_bt_controller_deinit
-.. doxygenfunction:: esp_bt_controller_enable
-.. doxygenfunction:: esp_bt_controller_disable
-.. doxygenfunction:: esp_bt_controller_get_status
-.. doxygenfunction:: esp_vhci_host_check_send_available
-.. doxygenfunction:: esp_vhci_host_send_packet
-.. doxygenfunction:: esp_vhci_host_register_callback
-
+.. include:: /_build/inc/bt.inc

docs/api-reference/bluetooth/esp_a2dp.rst

@@ -11,72 +11,12 @@ Overview
 Application Example
 -------------------
 
-Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following examples:
-
-:example:`bluetooth/a2dp_sink`
-
-  This is a A2DP sink client demo. This demo can be discovered and connected by A2DP source device and receive the audio stream from remote device.
+Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following application:
 
+* This is a A2DP sink client demo. This demo can be discovered and connected by A2DP source device and receive the audio stream from remote device - :example:`bluetooth/a2dp_sink`
 
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
-
-  * :component_file:`bt/bluedroid/api/include/esp_a2dp_api.h`
-
-Macros
-^^^^^^
-
-.. doxygendefine:: ESP_A2D_MCT_SBC
-.. doxygendefine:: ESP_A2D_MCT_M12
-.. doxygendefine:: ESP_A2D_MCT_M24
-.. doxygendefine:: ESP_A2D_MCT_ATRAC
-.. doxygendefine:: ESP_A2D_MCT_NON_A2DP
-.. doxygendefine:: ESP_A2D_CIE_LEN_SBC
-.. doxygendefine:: ESP_A2D_CIE_LEN_M12
-.. doxygendefine:: ESP_A2D_CIE_LEN_M24
-.. doxygendefine:: ESP_A2D_CIE_LEN_ATRAC
-
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-.. doxygentypedef:: esp_a2d_mct_t
-.. doxygentypedef:: esp_a2d_cb_t
-.. doxygentypedef:: esp_a2d_data_cb_t
-
-Enumerations
-^^^^^^^^^^^^
-
-.. doxygenenum:: esp_a2d_connection_state_t
-.. doxygenenum:: esp_a2d_disc_rsn_t
-.. doxygenenum:: esp_a2d_audio_state_t
-.. doxygenenum:: esp_a2d_cb_event_t
-
-Structures
-^^^^^^^^^^
-
-.. doxygenstruct:: esp_a2d_cb_param_t
-    :members:
-
-.. doxygenstruct:: esp_a2d_cb_param_t::a2d_conn_stat_param
-    :members:
-
-.. doxygenstruct:: esp_a2d_cb_param_t::a2d_audio_stat_param
-    :members:
-
-.. doxygenstruct:: esp_a2d_cb_param_t::a2d_audio_cfg_param
-    :members:
-
-
-Functions
-^^^^^^^^^
-
-.. doxygenfunction:: esp_a2d_register_callback
-.. doxygenfunction:: esp_a2d_register_data_callback
-.. doxygenfunction:: esp_a2d_sink_init
-.. doxygenfunction:: esp_a2d_sink_deinit
-.. doxygenfunction:: esp_a2d_sink_connect
-.. doxygenfunction:: esp_a2d_sink_disconnect
+.. include:: /_build/inc/esp_a2dp_api.inc
 

docs/api-reference/bluetooth/esp_avrc.rst

@@ -15,51 +15,9 @@ Application Example
 
 .. _Instructions: ../template.html
 
-
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
-
-  * :component_file:`bt/bluedroid/api/include/esp_avrc_api.h`
-
-
-Macros
-^^^^^^
-
-
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-.. doxygentypedef:: esp_avrc_ct_cb_t
-
-Enumerations
-^^^^^^^^^^^^
-
-.. doxygenenum:: esp_avrc_features_t
-.. doxygenenum:: esp_avrc_pt_cmd_t
-.. doxygenenum:: esp_avrc_pt_cmd_state_t
-.. doxygenenum:: esp_avrc_ct_cb_event_t
-
-Structures
-^^^^^^^^^^
-
-.. doxygenstruct:: esp_avrc_ct_cb_param_t
-    :members:
-
-.. doxygenstruct:: esp_avrc_ct_cb_param_t::avrc_ct_conn_stat_param
-    :members:
-
-.. doxygenstruct:: esp_avrc_ct_cb_param_t::avrc_ct_psth_rsp_param
-    :members:
-
-
-Functions
-^^^^^^^^^
+.. include:: /_build/inc/esp_avrc_api.inc
 
-.. doxygenfunction:: esp_avrc_ct_register_callback
-.. doxygenfunction:: esp_avrc_ct_init
-.. doxygenfunction:: esp_avrc_ct_deinit
-.. doxygenfunction:: esp_avrc_ct_send_passthrough_cmd
 

docs/api-reference/bluetooth/esp_blufi.rst

@@ -4,126 +4,20 @@ BLUFI API
 Overview
 --------
 BLUFI is a profile based GATT to config ESP32 WIFI to connect/disconnect AP or setup a softap and etc.
-Use should concern these things: 
+Use should concern these things:
+
 1. The event sent from profile. Then you need to do something as the event indicate.
 2. Security reference. You can write your own Security functions such as symmetrical encryption/decryption and checksum functions. Even you can define the "Key Exchange/Negotiation" procedure.
 
 Application Example
 -------------------
 
-Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following example:
-
-:example:`bluetooth/blufi` 
-
-  This is a BLUFI demo. This demo can set ESP32's wifi to softap/station/softap&station mode and config wifi connections.
+Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following application:
 
+* This is a BLUFI demo. This demo can set ESP32's wifi to softap/station/softap&station mode and config wifi connections - :example:`bluetooth/blufi`
 
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
-
-  * :component_file:`bt/bluedroid/api/include/esp_blufi_api.h`
-
-Macros
-^^^^^^
-
-
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-.. doxygentypedef:: esp_blufi_event_cb_t
-.. doxygentypedef:: esp_blufi_negotiate_data_handler_t
-.. doxygentypedef:: esp_blufi_encrypt_func_t
-.. doxygentypedef:: esp_blufi_decrypt_func_t
-.. doxygentypedef:: esp_blufi_checksum_func_t
-
-Enumerations
-^^^^^^^^^^^^
-
-.. doxygenenum:: esp_blufi_cb_event_t
-.. doxygenenum:: esp_blufi_sta_conn_state_t
-.. doxygenenum:: esp_blufi_init_state_t
-.. doxygenenum:: esp_blufi_deinit_state_t
-
-Structures
-^^^^^^^^^^
-
-.. doxygenstruct:: esp_blufi_extra_info_t
-    :members:
-
-.. doxygenstruct:: esp_blufi_cb_param_t
-    :members:
-
-.. doxygenstruct:: esp_blufi_cb_param_t::blufi_init_finish_evt_param
-    :members:
-
-.. doxygenstruct:: esp_blufi_cb_param_t::blufi_deinit_finish_evt_param
-    :members:
-
-.. doxygenstruct:: esp_blufi_cb_param_t::blufi_set_wifi_mode_evt_param
-    :members:
-
-.. doxygenstruct:: esp_blufi_cb_param_t::blufi_connect_evt_param
-    :members:
-
-.. doxygenstruct:: esp_blufi_cb_param_t::blufi_disconnect_evt_param
-    :members:
-
-.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_sta_bssid_evt_param
-    :members:
-
-.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_sta_ssid_evt_param
-    :members:
-
-.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_sta_passwd_evt_param
-    :members:
-
-.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_softap_ssid_evt_param
-    :members:
-
-.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_softap_passwd_evt_param
-    :members:
-
-.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_softap_max_conn_num_evt_param
-    :members:
-
-.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_softap_auth_mode_evt_param
-    :members:
-
-.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_softap_channel_evt_param
-    :members:
-
-.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_username_evt_param
-    :members:
-
-.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_ca_evt_param
-    :members:
-
-.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_client_cert_evt_param
-    :members:
-
-.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_server_cert_evt_param
-    :members:
-
-.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_client_pkey_evt_param
-    :members:
-
-.. doxygenstruct:: esp_blufi_cb_param_t::blufi_recv_server_pkey_evt_param
-    :members:
-
-.. doxygenstruct:: esp_blufi_callbacks_t
-    :members:
-
-
-Functions
-^^^^^^^^^
-
-.. doxygenfunction:: esp_blufi_register_callbacks
-.. doxygenfunction:: esp_blufi_profile_init
-.. doxygenfunction:: esp_blufi_profile_deinit
-.. doxygenfunction:: esp_blufi_send_wifi_conn_report
-.. doxygenfunction:: esp_blufi_get_version
-.. doxygenfunction:: esp_blufi_close
+.. include:: /_build/inc/esp_blufi_api.inc
 

docs/api-reference/bluetooth/esp_bt_defs.rst

@@ -17,49 +17,5 @@ Application Example
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
-
-  * :component_file:`bt/bluedroid/api/include/esp_bt_defs.h`
-
-
-Macros
-^^^^^^
-
-.. doxygendefine:: ESP_BT_OCTET16_LEN
-.. doxygendefine:: ESP_BT_OCTET8_LEN
-.. doxygendefine:: ESP_DEFAULT_GATT_IF
-.. doxygendefine:: ESP_BLE_CONN_PARAM_UNDEF
-.. doxygendefine:: ESP_BLE_IS_VALID_PARAM
-.. doxygendefine:: ESP_UUID_LEN_16
-.. doxygendefine:: ESP_UUID_LEN_32
-.. doxygendefine:: ESP_UUID_LEN_128
-.. doxygendefine:: ESP_BD_ADDR_LEN
-.. doxygendefine:: ESP_APP_ID_MIN
-.. doxygendefine:: ESP_APP_ID_MAX
-.. doxygendefine:: ESP_BD_ADDR_STR
-.. doxygendefine:: ESP_BD_ADDR_HEX
-
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-.. doxygentypedef:: esp_bt_octet16_t
-.. doxygentypedef:: esp_bt_octet8_t
-.. doxygentypedef:: esp_bd_addr_t
-
-Enumerations
-^^^^^^^^^^^^
-
-.. doxygenenum:: esp_bt_status_t
-.. doxygenenum:: esp_bt_dev_type_t
-.. doxygenenum:: esp_bd_addr_type_t
-.. doxygenenum:: esp_ble_addr_type_t
-
-Structures
-^^^^^^^^^^
-
-
-Functions
-^^^^^^^^^
-
+.. include:: /_build/inc/esp_bt_defs.inc
 

docs/api-reference/bluetooth/esp_bt_device.rst

@@ -15,35 +15,7 @@ Application Example
 
 .. _Instructions: ../template.html
 
-
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
-
-  * :component_file:`bt/bluedroid/api/include/esp_bt_device.h`
-
-
-Macros
-^^^^^^
-
-
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-
-Enumerations
-^^^^^^^^^^^^
-
-
-Structures
-^^^^^^^^^^
-
-
-Functions
-^^^^^^^^^
-
-.. doxygenfunction:: esp_bt_dev_get_address
-.. doxygenfunction:: esp_bt_dev_set_device_name
-
+.. include:: /_build/inc/esp_bt_device.inc

docs/api-reference/bluetooth/esp_bt_main.rst

@@ -17,36 +17,6 @@ Application Example
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
+.. include:: /_build/inc/esp_bt_main.inc
 
-  * :component_file:`bt/bluedroid/api/include/esp_bt_main.h`
-
-
-Macros
-^^^^^^
-
-
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-
-Enumerations
-^^^^^^^^^^^^
-
-.. doxygenenum:: esp_bluedroid_status_t
-
-
-Structures
-^^^^^^^^^^
-
-
-Functions
-^^^^^^^^^
-
-.. doxygenfunction:: esp_bluedroid_get_status
-.. doxygenfunction:: esp_bluedroid_enable
-.. doxygenfunction:: esp_bluedroid_disable
-.. doxygenfunction:: esp_bluedroid_init
-.. doxygenfunction:: esp_bluedroid_deinit
 

docs/api-reference/bluetooth/esp_gap_ble.rst

@@ -11,178 +11,12 @@ Overview
 Application Example
 -------------------
 
-Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following examples:
+Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following applications:
 
-:example:`bluetooth/gatt_server`, :example:`bluetooth/gatt_client` 
-
-  The two demos use different GAP APIs, such like advertising, scan, set device name and others.
+* The two demos use different GAP APIs, such like advertising, scan, set device name and others - :example:`bluetooth/gatt_server`, :example:`bluetooth/gatt_client`
 
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
-
-  * :component_file:`bt/bluedroid/api/include/esp_gap_ble_api.h`
-
-
-Macros
-^^^^^^
-
-.. doxygendefine:: ESP_BLE_ADV_FLAG_LIMIT_DISC
-.. doxygendefine:: ESP_BLE_ADV_FLAG_GEN_DISC
-.. doxygendefine:: ESP_BLE_ADV_FLAG_BREDR_NOT_SPT
-.. doxygendefine:: ESP_BLE_ADV_FLAG_DMT_CONTROLLER_SPT
-.. doxygendefine:: ESP_BLE_ADV_FLAG_DMT_HOST_SPT
-.. doxygendefine:: ESP_BLE_ADV_FLAG_NON_LIMIT_DISC
-.. doxygendefine:: ESP_LE_KEY_NONE
-.. doxygendefine:: ESP_LE_KEY_PENC
-.. doxygendefine:: ESP_LE_KEY_PID
-.. doxygendefine:: ESP_LE_KEY_PCSRK
-.. doxygendefine:: ESP_LE_KEY_PLK
-.. doxygendefine:: ESP_LE_KEY_LLK
-.. doxygendefine:: ESP_LE_KEY_LENC
-.. doxygendefine:: ESP_LE_KEY_LID
-.. doxygendefine:: ESP_LE_KEY_LCSRK
-.. doxygendefine:: ESP_LE_AUTH_NO_BOND
-.. doxygendefine:: ESP_LE_AUTH_BOND
-.. doxygendefine:: ESP_LE_AUTH_REQ_MITM
-.. doxygendefine:: ESP_LE_AUTH_REQ_SC_ONLY
-.. doxygendefine:: ESP_LE_AUTH_REQ_SC_BOND
-.. doxygendefine:: ESP_LE_AUTH_REQ_SC_MITM
-.. doxygendefine:: ESP_LE_AUTH_REQ_SC_MITM_BOND
-.. doxygendefine:: ESP_IO_CAP_OUT
-.. doxygendefine:: ESP_IO_CAP_IO
-.. doxygendefine:: ESP_IO_CAP_IN
-.. doxygendefine:: ESP_IO_CAP_NONE
-.. doxygendefine:: ESP_IO_CAP_KBDISP
-.. doxygendefine:: ESP_BLE_ADV_DATA_LEN_MAX
-.. doxygendefine:: ESP_BLE_SCAN_RSP_DATA_LEN_MAX
-
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-.. doxygentypedef:: esp_ble_key_type_t
-.. doxygentypedef:: esp_ble_auth_req_t
-.. doxygentypedef:: esp_ble_io_cap_t
-.. doxygentypedef:: esp_gap_ble_cb_t
-
-Enumerations
-^^^^^^^^^^^^
-
-.. doxygenenum:: esp_gap_ble_cb_event_t
-.. doxygenenum:: esp_ble_adv_data_type
-.. doxygenenum:: esp_ble_adv_type_t
-.. doxygenenum:: esp_ble_adv_channel_t
-.. doxygenenum:: esp_ble_adv_filter_t
-.. doxygenenum:: esp_ble_sec_act_t
-.. doxygenenum:: esp_ble_sm_param_t
-.. doxygenenum:: esp_ble_own_addr_src_t
-.. doxygenenum:: esp_ble_scan_type_t
-.. doxygenenum:: esp_ble_scan_filter_t
-.. doxygenenum:: esp_gap_search_evt_t
-.. doxygenenum:: esp_ble_evt_type_t
-
-Structures
-^^^^^^^^^^
-
-.. doxygenstruct:: esp_ble_adv_params_t
-    :members:
-
-.. doxygenstruct:: esp_ble_adv_data_t
-    :members:
-
-.. doxygenstruct:: esp_ble_scan_params_t
-    :members:
-
-.. doxygenstruct:: esp_ble_conn_update_params_t
-    :members:
-
-.. doxygenstruct:: esp_ble_penc_keys_t
-    :members:
-
-.. doxygenstruct:: esp_ble_pcsrk_keys_t
-    :members:
-
-.. doxygenstruct:: esp_ble_pid_keys_t
-    :members:
-
-.. doxygenstruct:: esp_ble_lenc_keys_t
-    :members:
-
-.. doxygenstruct:: esp_ble_lcsrk_keys
-    :members:
-
-.. doxygenstruct:: esp_ble_sec_key_notif_t
-    :members:
-
-.. doxygenstruct:: esp_ble_sec_req_t
-    :members:
-
-.. doxygenstruct:: esp_ble_key_value_t
-    :members:
-
-.. doxygenstruct:: esp_ble_key_t
-    :members:
-
-.. doxygenstruct:: esp_ble_local_id_keys_t
-    :members:
-
-.. doxygenstruct:: esp_ble_auth_cmpl_t
-    :members:
-
-.. doxygenstruct:: esp_ble_sec_t
-    :members:
-
-.. doxygenstruct:: esp_ble_gap_cb_param_t
-    :members:
-
-.. doxygenstruct:: esp_ble_gap_cb_param_t::ble_adv_data_cmpl_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gap_cb_param_t::ble_scan_rsp_data_cmpl_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gap_cb_param_t::ble_scan_param_cmpl_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gap_cb_param_t::ble_scan_result_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gap_cb_param_t::ble_adv_data_raw_cmpl_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gap_cb_param_t::ble_scan_rsp_data_raw_cmpl_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gap_cb_param_t::ble_adv_start_cmpl_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gap_cb_param_t::ble_scan_start_cmpl_evt_param
-    :members:
-
-
-Functions
-^^^^^^^^^
-
-.. doxygenfunction:: esp_ble_gap_register_callback
-.. doxygenfunction:: esp_ble_gap_config_adv_data
-.. doxygenfunction:: esp_ble_gap_set_scan_params
-.. doxygenfunction:: esp_ble_gap_start_scanning
-.. doxygenfunction:: esp_ble_gap_stop_scanning
-.. doxygenfunction:: esp_ble_gap_start_advertising
-.. doxygenfunction:: esp_ble_gap_stop_advertising
-.. doxygenfunction:: esp_ble_gap_update_conn_params
-.. doxygenfunction:: esp_ble_gap_set_pkt_data_len
-.. doxygenfunction:: esp_ble_gap_set_rand_addr
-.. doxygenfunction:: esp_ble_gap_config_local_privacy
-.. doxygenfunction:: esp_ble_gap_set_device_name
-.. doxygenfunction:: esp_ble_resolve_adv_data
-.. doxygenfunction:: esp_ble_gap_config_adv_data_raw
-.. doxygenfunction:: esp_ble_gap_config_scan_rsp_data_raw
-.. doxygenfunction:: esp_ble_gap_set_security_param
-.. doxygenfunction:: esp_ble_gap_security_rsp
-.. doxygenfunction:: esp_ble_set_encryption
-.. doxygenfunction:: esp_ble_passkey_reply
-.. doxygenfunction:: esp_ble_confirm_reply
+.. include:: /_build/inc/esp_gap_ble_api.inc
 

docs/api-reference/bluetooth/esp_gap_bt.rst

@@ -13,35 +13,8 @@ Application Example
 
 .. _Instructions: ../template.html
 
-
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
-
-  * :component_file:`bt/bluedroid/api/include/esp_gap_bt_api.h`
-
-
-Macros
-^^^^^^
-
-
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-
-Enumerations
-^^^^^^^^^^^^
-
-.. doxygenenum:: esp_bt_scan_mode_t
-
-Structures
-^^^^^^^^^^
-
-
-Functions
-^^^^^^^^^
-
-.. doxygenfunction:: esp_bt_gap_set_scan_mode
+.. include:: /_build/inc/esp_gap_bt_api.inc
 

docs/api-reference/bluetooth/esp_gatt_defs.rst

@@ -13,155 +13,9 @@ Application Example
 
 .. _Instructions: ../template.html
 
-
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
-
-  * :component_file:`bt/bluedroid/api/include/esp_gatt_defs.h`
-
-
-Macros
-^^^^^^
-
-.. doxygendefine:: ESP_GATT_UUID_IMMEDIATE_ALERT_SVC
-.. doxygendefine:: ESP_GATT_UUID_LINK_LOSS_SVC
-.. doxygendefine:: ESP_GATT_UUID_TX_POWER_SVC
-.. doxygendefine:: ESP_GATT_UUID_CURRENT_TIME_SVC
-.. doxygendefine:: ESP_GATT_UUID_REF_TIME_UPDATE_SVC
-.. doxygendefine:: ESP_GATT_UUID_NEXT_DST_CHANGE_SVC
-.. doxygendefine:: ESP_GATT_UUID_GLUCOSE_SVC
-.. doxygendefine:: ESP_GATT_UUID_HEALTH_THERMOM_SVC
-.. doxygendefine:: ESP_GATT_UUID_DEVICE_INFO_SVC
-.. doxygendefine:: ESP_GATT_UUID_HEART_RATE_SVC
-.. doxygendefine:: ESP_GATT_UUID_PHONE_ALERT_STATUS_SVC
-.. doxygendefine:: ESP_GATT_UUID_BATTERY_SERVICE_SVC
-.. doxygendefine:: ESP_GATT_UUID_BLOOD_PRESSURE_SVC
-.. doxygendefine:: ESP_GATT_UUID_ALERT_NTF_SVC
-.. doxygendefine:: ESP_GATT_UUID_HID_SVC
-.. doxygendefine:: ESP_GATT_UUID_SCAN_PARAMETERS_SVC
-.. doxygendefine:: ESP_GATT_UUID_RUNNING_SPEED_CADENCE_SVC
-.. doxygendefine:: ESP_GATT_UUID_CYCLING_SPEED_CADENCE_SVC
-.. doxygendefine:: ESP_GATT_UUID_CYCLING_POWER_SVC
-.. doxygendefine:: ESP_GATT_UUID_LOCATION_AND_NAVIGATION_SVC
-.. doxygendefine:: ESP_GATT_UUID_USER_DATA_SVC
-.. doxygendefine:: ESP_GATT_UUID_WEIGHT_SCALE_SVC
-.. doxygendefine:: ESP_GATT_UUID_PRI_SERVICE
-.. doxygendefine:: ESP_GATT_UUID_SEC_SERVICE
-.. doxygendefine:: ESP_GATT_UUID_INCLUDE_SERVICE
-.. doxygendefine:: ESP_GATT_UUID_CHAR_DECLARE
-.. doxygendefine:: ESP_GATT_UUID_CHAR_EXT_PROP
-.. doxygendefine:: ESP_GATT_UUID_CHAR_DESCRIPTION
-.. doxygendefine:: ESP_GATT_UUID_CHAR_CLIENT_CONFIG
-.. doxygendefine:: ESP_GATT_UUID_CHAR_SRVR_CONFIG
-.. doxygendefine:: ESP_GATT_UUID_CHAR_PRESENT_FORMAT
-.. doxygendefine:: ESP_GATT_UUID_CHAR_AGG_FORMAT
-.. doxygendefine:: ESP_GATT_UUID_CHAR_VALID_RANGE
-.. doxygendefine:: ESP_GATT_UUID_EXT_RPT_REF_DESCR
-.. doxygendefine:: ESP_GATT_UUID_RPT_REF_DESCR
-.. doxygendefine:: ESP_GATT_UUID_GAP_DEVICE_NAME
-.. doxygendefine:: ESP_GATT_UUID_GAP_ICON
-.. doxygendefine:: ESP_GATT_UUID_GAP_PREF_CONN_PARAM
-.. doxygendefine:: ESP_GATT_UUID_GAP_CENTRAL_ADDR_RESOL
-.. doxygendefine:: ESP_GATT_UUID_GATT_SRV_CHGD
-.. doxygendefine:: ESP_GATT_UUID_ALERT_LEVEL
-.. doxygendefine:: ESP_GATT_UUID_TX_POWER_LEVEL
-.. doxygendefine:: ESP_GATT_UUID_CURRENT_TIME
-.. doxygendefine:: ESP_GATT_UUID_LOCAL_TIME_INFO
-.. doxygendefine:: ESP_GATT_UUID_REF_TIME_INFO
-.. doxygendefine:: ESP_GATT_UUID_NW_STATUS
-.. doxygendefine:: ESP_GATT_UUID_NW_TRIGGER
-.. doxygendefine:: ESP_GATT_UUID_ALERT_STATUS
-.. doxygendefine:: ESP_GATT_UUID_RINGER_CP
-.. doxygendefine:: ESP_GATT_UUID_RINGER_SETTING
-.. doxygendefine:: ESP_GATT_UUID_GM_MEASUREMENT
-.. doxygendefine:: ESP_GATT_UUID_GM_CONTEXT
-.. doxygendefine:: ESP_GATT_UUID_GM_CONTROL_POINT
-.. doxygendefine:: ESP_GATT_UUID_GM_FEATURE
-.. doxygendefine:: ESP_GATT_UUID_SYSTEM_ID
-.. doxygendefine:: ESP_GATT_UUID_MODEL_NUMBER_STR
-.. doxygendefine:: ESP_GATT_UUID_SERIAL_NUMBER_STR
-.. doxygendefine:: ESP_GATT_UUID_FW_VERSION_STR
-.. doxygendefine:: ESP_GATT_UUID_HW_VERSION_STR
-.. doxygendefine:: ESP_GATT_UUID_SW_VERSION_STR
-.. doxygendefine:: ESP_GATT_UUID_MANU_NAME
-.. doxygendefine:: ESP_GATT_UUID_IEEE_DATA
-.. doxygendefine:: ESP_GATT_UUID_PNP_ID
-.. doxygendefine:: ESP_GATT_UUID_HID_INFORMATION
-.. doxygendefine:: ESP_GATT_UUID_HID_REPORT_MAP
-.. doxygendefine:: ESP_GATT_UUID_HID_CONTROL_POINT
-.. doxygendefine:: ESP_GATT_UUID_HID_REPORT
-.. doxygendefine:: ESP_GATT_UUID_HID_PROTO_MODE
-.. doxygendefine:: ESP_GATT_UUID_HID_BT_KB_INPUT
-.. doxygendefine:: ESP_GATT_UUID_HID_BT_KB_OUTPUT
-.. doxygendefine:: ESP_GATT_UUID_HID_BT_MOUSE_INPUT
-.. doxygendefine:: ESP_GATT_HEART_RATE_MEAS
-.. doxygendefine:: ESP_GATT_BODY_SENSOR_LOCATION
-.. doxygendefine:: ESP_GATT_HEART_RATE_CNTL_POINT
-.. doxygendefine:: ESP_GATT_UUID_BATTERY_LEVEL
-.. doxygendefine:: ESP_GATT_UUID_SC_CONTROL_POINT
-.. doxygendefine:: ESP_GATT_UUID_SENSOR_LOCATION
-.. doxygendefine:: ESP_GATT_UUID_RSC_MEASUREMENT
-.. doxygendefine:: ESP_GATT_UUID_RSC_FEATURE
-.. doxygendefine:: ESP_GATT_UUID_CSC_MEASUREMENT
-.. doxygendefine:: ESP_GATT_UUID_CSC_FEATURE
-.. doxygendefine:: ESP_GATT_UUID_SCAN_INT_WINDOW
-.. doxygendefine:: ESP_GATT_UUID_SCAN_REFRESH
-.. doxygendefine:: ESP_GATT_ILLEGAL_UUID
-.. doxygendefine:: ESP_GATT_ILLEGAL_HANDLE
-.. doxygendefine:: ESP_GATT_ATTR_HANDLE_MAX
-.. doxygendefine:: ESP_GATT_MAX_ATTR_LEN
-.. doxygendefine:: ESP_GATT_RSP_BY_APP
-.. doxygendefine:: ESP_GATT_AUTO_RSP
-.. doxygendefine:: ESP_GATT_IF_NONE
-
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-.. doxygentypedef:: esp_gatt_if_t
-
-Enumerations
-^^^^^^^^^^^^
-
-.. doxygenenum:: esp_gatt_prep_write_type
-.. doxygenenum:: esp_gatt_status_t
-.. doxygenenum:: esp_gatt_conn_reason_t
-.. doxygenenum:: esp_gatt_auth_req_t
-.. doxygenenum:: esp_gatt_perm_t
-.. doxygenenum:: esp_gatt_char_prop_t
-.. doxygenenum:: esp_gatt_write_type_t
-
-Structures
-^^^^^^^^^^
-
-.. doxygenstruct:: esp_attr_desc_t
-    :members:
-
-.. doxygenstruct:: esp_attr_control_t
-    :members:
-
-.. doxygenstruct:: esp_gatts_attr_db_t
-    :members:
-
-.. doxygenstruct:: esp_attr_value_t
-    :members:
-
-.. doxygenstruct:: esp_gatts_incl_svc_desc_t
-    :members:
-
-.. doxygenstruct:: esp_gatts_incl128_svc_desc_t
-    :members:
-
-.. doxygenstruct:: esp_gatt_value_t
-    :members:
-
-.. doxygenstruct:: esp_gatt_rsp_t
-    :members:
-
-
-Functions
-^^^^^^^^^
+.. include:: /_build/inc/esp_gatt_defs.inc
 
 

docs/api-reference/bluetooth/esp_gattc.rst

@@ -11,115 +11,12 @@ Overview
 Application Example
 -------------------
 
-Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following examples:
-
-:example:`bluetooth/gatt_client`
-
-  This is a GATT client demo. This demo can scan devices, connect to the GATT server and discover the service.
+Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following application:
 
+* This is a GATT client demo. This demo can scan devices, connect to the GATT server and discover the service :example:`bluetooth/gatt_client`
 
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
-
-  * :component_file:`bt/bluedroid/api/include/esp_gattc_api.h`
-
-Macros
-^^^^^^
-
-.. doxygendefine:: ESP_GATT_DEF_BLE_MTU_SIZE
-.. doxygendefine:: ESP_GATT_MAX_MTU_SIZE
-
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-.. doxygentypedef:: esp_gattc_cb_t
-
-Enumerations
-^^^^^^^^^^^^
-
-.. doxygenenum:: esp_gattc_cb_event_t
-
-Structures
-^^^^^^^^^^
-
-.. doxygenstruct:: esp_ble_gattc_cb_param_t
-    :members:
-
-.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_reg_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_open_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_close_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_cfg_mtu_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_search_cmpl_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_search_res_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_read_char_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_write_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_exec_cmpl_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_notify_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_srvc_chg_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_congest_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_get_char_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_get_descr_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_get_incl_srvc_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_reg_for_notify_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gattc_cb_param_t::gattc_unreg_for_notify_evt_param
-    :members:
-
-
-Functions
-^^^^^^^^^
-
-.. doxygenfunction:: esp_ble_gattc_register_callback
-.. doxygenfunction:: esp_ble_gattc_app_register
-.. doxygenfunction:: esp_ble_gattc_app_unregister
-.. doxygenfunction:: esp_ble_gattc_open
-.. doxygenfunction:: esp_ble_gattc_close
-.. doxygenfunction:: esp_ble_gattc_config_mtu
-.. doxygenfunction:: esp_ble_gattc_search_service
-.. doxygenfunction:: esp_ble_gattc_get_characteristic
-.. doxygenfunction:: esp_ble_gattc_get_descriptor
-.. doxygenfunction:: esp_ble_gattc_get_included_service
-.. doxygenfunction:: esp_ble_gattc_read_char
-.. doxygenfunction:: esp_ble_gattc_read_char_descr
-.. doxygenfunction:: esp_ble_gattc_write_char
-.. doxygenfunction:: esp_ble_gattc_write_char_descr
-.. doxygenfunction:: esp_ble_gattc_prepare_write
-.. doxygenfunction:: esp_ble_gattc_prepare_write_char_descr
-.. doxygenfunction:: esp_ble_gattc_execute_write
-.. doxygenfunction:: esp_ble_gattc_register_for_notify
-.. doxygenfunction:: esp_ble_gattc_unregister_for_notify
+.. include:: /_build/inc/esp_gattc_api.inc
 

docs/api-reference/bluetooth/esp_gatts.rst

@@ -11,118 +11,12 @@ Overview
 Application Example
 -------------------
 
-Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following example:
+Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following application:
 
-:example:`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.
+* 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 - :example:`bluetooth/gatt_server`
 
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
-
-  * :component_file:`bt/bluedroid/api/include/esp_gatts_api.h`
-
-Macros
-^^^^^^
-
-.. doxygendefine:: ESP_GATT_PREP_WRITE_CANCEL
-.. doxygendefine:: ESP_GATT_PREP_WRITE_EXEC
-
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-.. doxygentypedef:: esp_gatts_cb_t
-
-Enumerations
-^^^^^^^^^^^^
-
-.. doxygenenum:: esp_gatts_cb_event_t
-
-Structures
-^^^^^^^^^^
-
-.. doxygenstruct:: esp_ble_gatts_cb_param_t
-    :members:
-
-.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_reg_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_read_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_write_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_exec_write_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_mtu_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_conf_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_create_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_add_incl_srvc_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_add_char_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_add_char_descr_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_delete_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_start_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_stop_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_connect_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_disconnect_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_congest_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_rsp_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_add_attr_tab_evt_param
-    :members:
-
-.. doxygenstruct:: esp_ble_gatts_cb_param_t::gatts_set_attr_val_evt_param
-    :members:
-
-
-Functions
-^^^^^^^^^
-
-.. doxygenfunction:: esp_ble_gatts_register_callback
-.. doxygenfunction:: esp_ble_gatts_app_register
-.. doxygenfunction:: esp_ble_gatts_app_unregister
-.. doxygenfunction:: esp_ble_gatts_create_service
-.. doxygenfunction:: esp_ble_gatts_create_attr_tab
-.. doxygenfunction:: esp_ble_gatts_add_included_service
-.. doxygenfunction:: esp_ble_gatts_add_char
-.. doxygenfunction:: esp_ble_gatts_add_char_descr
-.. doxygenfunction:: esp_ble_gatts_delete_service
-.. doxygenfunction:: esp_ble_gatts_start_service
-.. doxygenfunction:: esp_ble_gatts_stop_service
-.. doxygenfunction:: esp_ble_gatts_send_indicate
-.. doxygenfunction:: esp_ble_gatts_send_response
-.. doxygenfunction:: esp_ble_gatts_set_attr_value
-.. doxygenfunction:: esp_ble_gatts_get_attr_value
-.. doxygenfunction:: esp_ble_gatts_open
-.. doxygenfunction:: esp_ble_gatts_close
+.. include:: /_build/inc/esp_gatts_api.inc
 

docs/api-reference/bluetooth/index.rst

@@ -7,7 +7,7 @@ Bluetooth API
    Bluetooth Controller && VHCI <controller_vhci>
    Bluetooth Common <bt_common>
    Bluetooth LE <bt_le>
-   Bluetooth Classic BT <classic_bt>
+   Bluetooth Classic <classic_bt>
 
 
 Example code for this API section is provided in :example:`bluetooth` directory of ESP-IDF examples.

docs/api-reference/ethernet/esp_eth.rst

@@ -6,69 +6,42 @@ Application Example
 
 Ethernet example: :example:`ethernet/ethernet`.
 
-API Reference
--------------
-
-Header Files
-^^^^^^^^^^^^
-
-  * :component_file:`ethernet/include/esp_eth.h`
-    * :component_file:`ethernet/include/phy/phy.h`
-
 PHY Interfaces
-^^^^^^^^^^^^^^
+--------------
 
 The configured PHY model(s) are set in software by configuring the eth_config_t structure for the given PHY.
 
 Headers include a default configuration structure. These default configurations will need some members overriden or re-set before they can be used for a particular PHY hardware configuration. Consult the Ethernet example to see how this is done.
 
-  * :component_file:`ethernet/include/phy/phy_tlk110.h`
-  * :component_file:`ethernet/include/phy/phy_lan8720.h`
+  * :component_file:`ethernet/include/eth_phy/phy.h` (common)
+  * :component_file:`ethernet/include/eth_phy/phy_tlk110.h`
+  * :component_file:`ethernet/include/eth_phy/phy_lan8720.h`
+
+PHY Configuration Constants
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Type Definitions
-^^^^^^^^^^^^^^^^
+.. doxygenvariable:: phy_tlk110_default_ethernet_config
+.. doxygenvariable:: phy_lan8720_default_ethernet_config
 
-.. doxygentypedef:: eth_phy_check_link_func
-.. doxygentypedef:: eth_phy_check_init_func
-.. doxygentypedef:: eth_phy_get_speed_mode_func
-.. doxygentypedef:: eth_phy_get_duplex_mode_func
-.. doxygentypedef:: eth_phy_func
-.. doxygentypedef:: eth_tcpip_input_func
-.. doxygentypedef:: eth_gpio_config_func
-.. doxygentypedef:: eth_phy_get_partner_pause_enable_func
 
-Enumerations
-^^^^^^^^^^^^
+API Reference - Ethernet
+------------------------
 
-.. doxygenenum:: eth_mode_t
-.. doxygenenum:: eth_speed_mode_t
-.. doxygenenum:: eth_duplex_mode_t
-.. doxygenenum:: eth_phy_base_t
+.. include:: /_build/inc/esp_eth.inc
 
-Structures
-^^^^^^^^^^
+API Reference - PHY Common
+--------------------------
 
-.. doxygenstruct:: eth_config_t
-    :members:
+.. include:: /_build/inc/phy.inc
 
+API Reference - PHY TLK110
+--------------------------
 
-Functions
-^^^^^^^^^
+.. include:: /_build/inc/phy_tlk110.inc
 
-.. doxygenfunction:: esp_eth_init
-.. doxygenfunction:: esp_eth_tx
-.. doxygenfunction:: esp_eth_enable
-.. doxygenfunction:: esp_eth_disable
-.. doxygenfunction:: esp_eth_get_mac
-.. doxygenfunction:: esp_eth_smi_write
-.. doxygenfunction:: esp_eth_smi_read
-.. doxygenfunction:: esp_eth_smi_wait_value
-.. doxygenfunction:: esp_eth_smi_wait_set
-.. doxygenfunction:: esp_eth_free_rx_buf
+API Reference - PHY LAN8720
+---------------------------
 
+.. include:: /_build/inc/phy_lan8720.inc
 
-PHY Configuration Constants
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. doxygenvariable:: phy_tlk110_default_ethernet_config
-.. doxygenvariable:: phy_lan8720_default_ethernet_config

docs/api-reference/index.rst

@@ -9,6 +9,7 @@ API Reference
    Bluetooth <bluetooth/index>
    Ethernet <ethernet/index>
    Peripherals <peripherals/index>
-   System <system/index>
-   Storage <storage/index>
    Protocols <protocols/index>
+   Storage <storage/index>
+   System <system/index>
+

docs/api-reference/peripherals/adc.rst

@@ -40,23 +40,6 @@ The value read in both these examples is 12 bits wide (range 0-4095).
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
+.. include:: /_build/inc/adc.inc
 
-  * `components/driver/include/driver/adc.h`
-
-Enumerations
-^^^^^^^^^^^^
-
-  .. doxygenenum:: adc1_channel_t
-  .. doxygenenum:: adc_atten_t
-  .. doxygenenum:: adc_bits_width_t
-
-Functions
-^^^^^^^^^
-
-  .. doxygenfunction:: adc1_config_width
-  .. doxygenfunction:: adc1_config_channel_atten
-  .. doxygenfunction:: adc1_get_voltage
-  .. doxygenfunction:: hall_sensor_read
 

docs/api-reference/peripherals/dac.rst

@@ -28,22 +28,5 @@ Setting DAC channel 1 (GPIO 25) voltage to approx 0.78 of VDD_A voltage (VDD * 2
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
+.. include:: /_build/inc/dac.inc
 
-  * `components/driver/include/driver/dac.h`
-
-Enumerations
-^^^^^^^^^^^^
-
-  .. doxygenenum:: dac_channel_t
-
-Functions
-^^^^^^^^^
-
-  .. doxygenfunction:: dac_output_voltage
-  .. doxygenfunction:: dac_output_enable
-  .. doxygenfunction:: dac_output_disable
-  .. doxygenfunction:: dac_i2s_enable
-  .. doxygenfunction:: dac_i2s_disable
-  

docs/api-reference/peripherals/gpio.rst

@@ -16,176 +16,13 @@ Application Example
 
 GPIO output and input interrupt example: :example:`peripherals/gpio`.
 
-API Reference
--------------
+API Reference - Normal GPIO
+---------------------------
 
-Header Files
-^^^^^^^^^^^^
+.. include:: /_build/inc/gpio.inc
 
-  * :component_file:`driver/include/driver/gpio.h`
-  * :component_file:`driver/include/driver/rtc_io.h`
+API Reference - RTC GPIO
+------------------------
 
-Macros
-^^^^^^
+.. include:: /_build/inc/rtc_io.inc
 
-Normal GPIO
-~~~~~~~~~~~
-
-.. doxygendefine:: GPIO_SEL_0
-.. doxygendefine:: GPIO_SEL_1
-.. doxygendefine:: GPIO_SEL_2
-.. doxygendefine:: GPIO_SEL_3
-.. doxygendefine:: GPIO_SEL_4
-.. doxygendefine:: GPIO_SEL_5
-.. doxygendefine:: GPIO_SEL_6
-.. doxygendefine:: GPIO_SEL_7
-.. doxygendefine:: GPIO_SEL_8
-.. doxygendefine:: GPIO_SEL_9
-.. doxygendefine:: GPIO_SEL_10
-.. doxygendefine:: GPIO_SEL_11
-.. doxygendefine:: GPIO_SEL_12
-.. doxygendefine:: GPIO_SEL_13
-.. doxygendefine:: GPIO_SEL_14
-.. doxygendefine:: GPIO_SEL_15
-.. doxygendefine:: GPIO_SEL_16
-.. doxygendefine:: GPIO_SEL_17
-.. doxygendefine:: GPIO_SEL_18
-.. doxygendefine:: GPIO_SEL_19
-.. doxygendefine:: GPIO_SEL_21
-.. doxygendefine:: GPIO_SEL_22
-.. doxygendefine:: GPIO_SEL_23
-.. doxygendefine:: GPIO_SEL_25
-.. doxygendefine:: GPIO_SEL_26
-.. doxygendefine:: GPIO_SEL_27
-.. doxygendefine:: GPIO_SEL_32
-.. doxygendefine:: GPIO_SEL_33
-.. doxygendefine:: GPIO_SEL_34
-.. doxygendefine:: GPIO_SEL_35
-.. doxygendefine:: GPIO_SEL_36
-.. doxygendefine:: GPIO_SEL_37
-.. doxygendefine:: GPIO_SEL_38
-.. doxygendefine:: GPIO_SEL_39
-.. doxygendefine:: GPIO_PIN_REG_0
-.. doxygendefine:: GPIO_PIN_REG_1
-.. doxygendefine:: GPIO_PIN_REG_2
-.. doxygendefine:: GPIO_PIN_REG_3
-.. doxygendefine:: GPIO_PIN_REG_4
-.. doxygendefine:: GPIO_PIN_REG_5
-.. doxygendefine:: GPIO_PIN_REG_6
-.. doxygendefine:: GPIO_PIN_REG_7
-.. doxygendefine:: GPIO_PIN_REG_8
-.. doxygendefine:: GPIO_PIN_REG_9
-.. doxygendefine:: GPIO_PIN_REG_10
-.. doxygendefine:: GPIO_PIN_REG_11
-.. doxygendefine:: GPIO_PIN_REG_12
-.. doxygendefine:: GPIO_PIN_REG_13
-.. doxygendefine:: GPIO_PIN_REG_14
-.. doxygendefine:: GPIO_PIN_REG_15
-.. doxygendefine:: GPIO_PIN_REG_16
-.. doxygendefine:: GPIO_PIN_REG_17
-.. doxygendefine:: GPIO_PIN_REG_18
-.. doxygendefine:: GPIO_PIN_REG_19
-.. doxygendefine:: GPIO_PIN_REG_20
-.. doxygendefine:: GPIO_PIN_REG_21
-.. doxygendefine:: GPIO_PIN_REG_22
-.. doxygendefine:: GPIO_PIN_REG_23
-.. doxygendefine:: GPIO_PIN_REG_25
-.. doxygendefine:: GPIO_PIN_REG_26
-.. doxygendefine:: GPIO_PIN_REG_27
-.. doxygendefine:: GPIO_PIN_REG_32
-.. doxygendefine:: GPIO_PIN_REG_33
-.. doxygendefine:: GPIO_PIN_REG_34
-.. doxygendefine:: GPIO_PIN_REG_35
-.. doxygendefine:: GPIO_PIN_REG_36
-.. doxygendefine:: GPIO_PIN_REG_37
-.. doxygendefine:: GPIO_PIN_REG_38
-.. doxygendefine:: GPIO_PIN_REG_39
-.. doxygendefine:: GPIO_APP_CPU_INTR_ENA
-.. doxygendefine:: GPIO_APP_CPU_NMI_INTR_ENA
-.. doxygendefine:: GPIO_PRO_CPU_INTR_ENA
-.. doxygendefine:: GPIO_PRO_CPU_NMI_INTR_ENA
-.. doxygendefine:: GPIO_SDIO_EXT_INTR_ENA
-.. doxygendefine:: GPIO_MODE_DEF_INPUT
-.. doxygendefine:: GPIO_MODE_DEF_OUTPUT
-.. doxygendefine:: GPIO_MODE_DEF_OD
-.. doxygendefine:: GPIO_PIN_COUNT
-.. doxygendefine:: GPIO_IS_VALID_GPIO
-.. doxygendefine:: GPIO_IS_VALID_OUTPUT_GPIO
-
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-Normal GPIO
-~~~~~~~~~~~
-
-.. doxygentypedef:: gpio_isr_t
-.. doxygentypedef:: gpio_isr_handle_t
-
-Enumerations
-^^^^^^^^^^^^
-
-Normal GPIO
-~~~~~~~~~~~
-
-.. doxygenenum:: gpio_num_t
-.. doxygenenum:: gpio_int_type_t
-.. doxygenenum:: gpio_mode_t
-.. doxygenenum:: gpio_pullup_t
-.. doxygenenum:: gpio_pulldown_t
-.. doxygenenum:: gpio_pull_mode_t
-
-RTC GPIO
-~~~~~~~~
-
-.. doxygenenum:: rtc_gpio_mode_t
-
-Structures
-^^^^^^^^^^
-
-Normal GPIO
-~~~~~~~~~~~
-
-.. doxygenstruct:: gpio_config_t
-    :members:
-
-Functions
-^^^^^^^^^
-
-Normal GPIO
-~~~~~~~~~~~
-
-.. 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
-.. doxygenfunction:: gpio_pullup_en
-.. doxygenfunction:: gpio_pullup_dis
-.. doxygenfunction:: gpio_pulldown_en
-.. doxygenfunction:: gpio_pulldown_dis
-.. doxygenfunction:: gpio_install_isr_service
-.. doxygenfunction:: gpio_uninstall_isr_service
-.. doxygenfunction:: gpio_isr_handler_add
-.. doxygenfunction:: gpio_isr_handler_remove
-
-
-RTC GPIO
-~~~~~~~~
-
-.. doxygenfunction:: rtc_gpio_is_valid_gpio
-.. doxygenfunction:: rtc_gpio_init
-.. doxygenfunction:: rtc_gpio_deinit
-.. doxygenfunction:: rtc_gpio_get_level
-.. doxygenfunction:: rtc_gpio_set_level
-.. doxygenfunction:: rtc_gpio_set_direction
-.. doxygenfunction:: rtc_gpio_pullup_en
-.. doxygenfunction:: rtc_gpio_pulldown_en
-.. doxygenfunction:: rtc_gpio_pullup_dis
-.. doxygenfunction:: rtc_gpio_pulldown_dis
-.. doxygenfunction:: rtc_gpio_unhold_all

docs/api-reference/peripherals/i2c.rst

@@ -1,5 +1,5 @@
 I2C
-===========
+===
 
 Overview
 --------
@@ -14,69 +14,5 @@ I2C master and slave example: :example:`peripherals/i2c`.
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
-
-  * :component_file:`driver/include/driver/i2c.h`
-
-Macros
-^^^^^^
-
-.. doxygendefine:: I2C_APB_CLK_FREQ
-.. doxygendefine:: I2C_FIFO_LEN
-
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-.. doxygentypedef:: i2c_cmd_handle_t
-
-Enumerations
-^^^^^^^^^^^^
-
-.. doxygenenum:: i2c_mode_t
-.. doxygenenum:: i2c_rw_t
-.. doxygenenum:: i2c_trans_mode_t
-.. doxygenenum:: i2c_opmode_t
-.. doxygenenum:: i2c_port_t
-.. doxygenenum:: i2c_addr_mode_t
-
-Structures
-^^^^^^^^^^
-
-.. doxygenstruct:: i2c_config_t
-    :members:
-
-
-Functions
-^^^^^^^^^
-
-.. doxygenfunction:: i2c_driver_install
-.. doxygenfunction:: i2c_driver_delete
-.. doxygenfunction:: i2c_param_config
-.. doxygenfunction:: i2c_reset_tx_fifo
-.. doxygenfunction:: i2c_reset_rx_fifo
-.. doxygenfunction:: i2c_isr_register
-.. doxygenfunction:: i2c_isr_free
-.. doxygenfunction:: i2c_set_pin
-.. doxygenfunction:: i2c_master_start
-.. doxygenfunction:: i2c_master_write_byte
-.. doxygenfunction:: i2c_master_write
-.. doxygenfunction:: i2c_master_read_byte
-.. doxygenfunction:: i2c_master_read
-.. doxygenfunction:: i2c_master_stop
-.. doxygenfunction:: i2c_master_cmd_begin
-.. doxygenfunction:: i2c_slave_write_buffer
-.. doxygenfunction:: i2c_slave_read
-.. doxygenfunction:: i2c_set_period
-.. doxygenfunction:: i2c_get_period
-.. doxygenfunction:: i2c_set_start_timing
-.. doxygenfunction:: i2c_get_start_timing
-.. doxygenfunction:: i2c_set_stop_timing
-.. doxygenfunction:: i2c_get_stop_timing
-.. doxygenfunction:: i2c_set_data_timing
-.. doxygenfunction:: i2c_get_data_timing
-.. doxygenfunction:: i2c_set_data_mode
-.. doxygenfunction:: i2c_get_data_mode
-.. doxygenfunction:: i2c_cmd_link_create
-.. doxygenfunction:: i2c_cmd_link_delete
+.. include:: /_build/inc/i2c.inc
 

docs/api-reference/peripherals/i2s.rst

@@ -15,7 +15,11 @@ Application Example
 
 A full I2S example is available in esp-idf: :example:`peripherals/i2s`.
 
-Short example of I2S configuration::
+Short example of I2S configuration:
+
+.. highlight:: c
+
+::
 
     #include "driver/i2s.h"
     #include "freertos/queue.h"
@@ -84,53 +88,5 @@ Short example configuring I2S to use internal DAC for analog output::
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
-
-  * `components/driver/include/driver/i2s.h`
-
-Data Structures
-^^^^^^^^^^^^^^^
-
-  .. doxygenstruct:: i2s_config_t
-     :members:
-  .. doxygenstruct:: i2s_event_t
-     :members:
-  .. doxygenstruct:: i2s_pin_config_t
-     :members:
-
-Macros
-^^^^^^
-
-  .. doxygendefine:: I2S_PIN_NO_CHANGE
-
-Enumerations
-^^^^^^^^^^^^
-
-  .. doxygenenum:: i2s_bits_per_sample_t
-  .. doxygenenum:: i2s_comm_format_t
-  .. doxygenenum:: i2s_channel_fmt_t
-  .. doxygenenum:: pdm_sample_rate_ratio_t
-  .. doxygenenum:: pdm_pcm_conv_t
-  .. doxygenenum:: i2s_port_t
-  .. doxygenenum:: i2s_mode_t
-  .. doxygenenum:: i2s_event_type_t
-  .. doxygenenum:: i2s_dac_mode_t
-
-Functions
-^^^^^^^^^
-
-  .. doxygenfunction:: i2s_set_pin
-  .. doxygenfunction:: i2s_set_dac_mode
-  .. doxygenfunction:: i2s_driver_install
-  .. doxygenfunction:: i2s_driver_uninstall
-  .. doxygenfunction:: i2s_write_bytes
-  .. doxygenfunction:: i2s_read_bytes
-  .. doxygenfunction:: i2s_push_sample
-  .. doxygenfunction:: i2s_pop_sample
-  .. doxygenfunction:: i2s_set_sample_rates
-  .. doxygenfunction:: i2s_start
-  .. doxygenfunction:: i2s_stop
-  .. doxygenfunction:: i2s_zero_dma_buffer
-
+.. include:: /_build/inc/i2s.inc
 

docs/api-reference/peripherals/index.rst

@@ -10,12 +10,13 @@ Peripherals API
    I2C <i2c>
    I2S <i2s>
    LED Control <ledc>
+   MCPWM <mcpwm>
    Pulse Counter <pcnt>
+   Remote Control <rmt>
    SD/MMC Card Host <../storage/sdmmc>
    Sigma-delta Modulation <sigmadelta>
    SPI Master <spi_master>
    SPI Slave <spi_slave>
-   Remote Control <rmt>
    Timer <timer>
    UART <uart>
 

docs/api-reference/peripherals/ledc.rst

@@ -17,64 +17,5 @@ LEDC change duty cycle and fading control example: :example:`peripherals/ledc`.
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
-
-  * :component_file:`driver/include/driver/ledc.h`
-
-Macros
-^^^^^^
-
-.. doxygendefine:: LEDC_APB_CLK_HZ
-.. doxygendefine:: LEDC_REF_CLK_HZ
-
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-.. doxygentypedef:: ledc_isr_handle_t
-
-Enumerations
-^^^^^^^^^^^^
-
-.. doxygenenum:: ledc_mode_t
-.. doxygenenum:: ledc_intr_type_t
-.. doxygenenum:: ledc_duty_direction_t
-.. doxygenenum:: ledc_clk_src_t
-.. doxygenenum:: ledc_timer_t
-.. doxygenenum:: ledc_channel_t
-.. doxygenenum:: ledc_timer_bit_t
-
-Structures
-^^^^^^^^^^
-
-.. doxygenstruct:: ledc_channel_config_t
-    :members:
-
-.. doxygenstruct:: ledc_timer_config_t
-    :members:
-
-
-Functions
-^^^^^^^^^
-
-.. doxygenfunction:: ledc_channel_config
-.. doxygenfunction:: ledc_timer_config
-.. doxygenfunction:: ledc_update_duty
-.. doxygenfunction:: ledc_stop
-.. doxygenfunction:: ledc_set_freq
-.. doxygenfunction:: ledc_get_freq
-.. doxygenfunction:: ledc_set_duty
-.. doxygenfunction:: ledc_get_duty
-.. doxygenfunction:: ledc_set_fade
-.. doxygenfunction:: ledc_isr_register
-.. doxygenfunction:: ledc_timer_set
-.. doxygenfunction:: ledc_timer_rst
-.. doxygenfunction:: ledc_timer_pause
-.. doxygenfunction:: ledc_timer_resume
-.. doxygenfunction:: ledc_bind_channel_timer
-.. doxygenfunction:: ledc_set_fade_with_step
-.. doxygenfunction:: ledc_set_fade_with_time
-.. doxygenfunction:: ledc_fade_func_install
-.. doxygenfunction:: ledc_fade_func_uninstall
-.. doxygenfunction:: ledc_fade_start
+.. include:: /_build/inc/ledc.inc
 

docs/api/peripherals/mcpwm.rst → docs/api-reference/peripherals/mcpwm.rst

@@ -50,84 +50,11 @@ The block diagram of MCPWM unit is as shown.
 Application Example
 -------------------
 
-MCPWM different motor example: :example:`peripherals/mcpwm`.
+Examples of using MCPWM for motor control: :example:`peripherals/mcpwm`.
 
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
+.. include:: /_build/inc/mcpwm.inc
 
-  * :component_file:`driver/include/driver/mcpwm.h`
-    
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-
-Enumerations
-^^^^^^^^^^^^
-
-.. doxygenenum:: mcpwm_io_signals_t
-.. doxygenenum:: mcpwm_unit_t
-.. doxygenenum:: mcpwm_timer_t
-.. doxygenenum:: mcpwm_operator_t
-.. doxygenenum:: mcpwm_counter_type_t
-.. doxygenenum:: mcpwm_duty_type_t
-.. doxygenenum:: mcpwm_carrier_os_t
-.. doxygenenum:: mcpwm_carrier_out_ivt_t
-.. doxygenenum:: mcpwm_sync_signal_t
-.. doxygenenum:: mcpwm_fault_signal_t
-.. doxygenenum:: mcpwm_fault_input_level_t
-.. doxygenenum:: mcpwm_action_on_pwmxa_t
-.. doxygenenum:: mcpwm_action_on_pwmxb_t
-.. doxygenenum:: mcpwm_capture_signal_t
-.. doxygenenum:: mcpwm_capture_on_edge_t
-.. doxygenenum:: mcpwm_deadtime_type_t
-
-Structures
-^^^^^^^^^^
-
-.. doxygenstruct:: mcpwm_config_t
-    :members:
-
-.. doxygenstruct:: mcpwm_carrier_config_t
-    :members:
-
-
-Functions
-^^^^^^^^^
-
-.. doxygenfunction:: mcpwm_gpio_init
-.. doxygenfunction:: mcpwm_init
-.. doxygenfunction:: mcpwm_set_frequency
-.. doxygenfunction:: mcpwm_set_duty
-.. doxygenfunction:: mcpwm_set_duty_in_us
-.. doxygenfunction:: mcpwm_set_duty_type
-.. doxygenfunction:: mcpwm_get_frequency
-.. doxygenfunction:: mcpwm_get_duty
-.. doxygenfunction:: mcpwm_set_signal_high
-.. doxygenfunction:: mcpwm_set_signal_low
-.. doxygenfunction:: mcpwm_start
-.. doxygenfunction:: mcpwm_stop
-.. doxygenfunction:: mcpwm_carrier_init
-.. doxygenfunction:: mcpwm_carrier_enable
-.. doxygenfunction:: mcpwm_carrier_disable
-.. doxygenfunction:: mcpwm_carrier_set_period
-.. doxygenfunction:: mcpwm_carrier_set_duty_cycle
-.. doxygenfunction:: mcpwm_carrier_oneshot_mode_enable
-.. doxygenfunction:: mcpwm_carrier_oneshot_mode_disable
-.. doxygenfunction:: mcpwm_carrier_output_invert
-.. doxygenfunction:: mcpwm_deadtime_enable
-.. doxygenfunction:: mcpwm_deadtime_disable
-.. doxygenfunction:: mcpwm_fault_init
-.. doxygenfunction:: mcpwm_fault_set_oneshot_mode
-.. doxygenfunction:: mcpwm_fault_set_cyc_mode
-.. doxygenfunction:: mcpwm_fault_deinit
-.. doxygenfunction:: mcpwm_capture_enable
-.. doxygenfunction:: mcpwm_capture_disable
-.. doxygenfunction:: mcpwm_capture_signal_get_value
-.. doxygenfunction:: mcpwm_capture_signal_get_edge
-.. doxygenfunction:: mcpwm_sync_enable
-.. doxygenfunction:: mcpwm_sync_disable
-.. doxygenfunction:: mcpwm_isr_register
 

docs/api-reference/peripherals/pcnt.rst

@@ -14,53 +14,5 @@ Pulse counter with control signal and event interrupt example: :example:`periphe
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
-
-  * :component_file:`driver/include/driver/pcnt.h`
-
-
-Macros
-^^^^^^
-
-
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-
-Enumerations
-^^^^^^^^^^^^
-
-.. doxygenenum:: pcnt_ctrl_mode_t
-.. doxygenenum:: pcnt_count_mode_t
-.. doxygenenum:: pcnt_unit_t
-.. doxygenenum:: pcnt_channel_t
-.. doxygenenum:: pcnt_evt_type_t
-
-Structures
-^^^^^^^^^^
-
-.. doxygenstruct:: pcnt_config_t
-
-Functions
-^^^^^^^^^
-
-.. doxygenfunction:: pcnt_unit_config
-.. doxygenfunction:: pcnt_get_counter_value
-.. doxygenfunction:: pcnt_counter_pause
-.. doxygenfunction:: pcnt_counter_resume
-.. doxygenfunction:: pcnt_counter_clear
-.. doxygenfunction:: pcnt_intr_enable
-.. doxygenfunction:: pcnt_intr_disable
-.. doxygenfunction:: pcnt_event_enable
-.. doxygenfunction:: pcnt_event_disable
-.. doxygenfunction:: pcnt_set_event_value
-.. doxygenfunction:: pcnt_get_event_value
-.. doxygenfunction:: pcnt_isr_register
-.. doxygenfunction:: pcnt_set_pin
-.. doxygenfunction:: pcnt_filter_enable
-.. doxygenfunction:: pcnt_filter_disable
-.. doxygenfunction:: pcnt_set_filter_value
-.. doxygenfunction:: pcnt_get_filter_value
-.. doxygenfunction:: pcnt_set_mode
+.. include:: /_build/inc/pcnt.inc
 

docs/api-reference/peripherals/rmt.rst

@@ -14,80 +14,5 @@ NEC remote control TX and RX example: :example:`peripherals/rmt_nec_tx_rx`.
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
-
-  * :component_file:`driver/include/driver/rmt.h`
-
-Macros
-^^^^^^
-
-.. doxygendefine:: RMT_MEM_BLOCK_BYTE_NUM
-.. doxygendefine:: RMT_MEM_ITEM_NUM
-
-Enumerations
-^^^^^^^^^^^^
-
-.. doxygenenum:: rmt_channel_t
-.. doxygenenum:: rmt_mem_owner_t
-.. doxygenenum:: rmt_source_clk_t
-.. doxygenenum:: rmt_data_mode_t
-.. doxygenenum:: rmt_mode_t
-.. doxygenenum:: rmt_idle_level_t
-.. doxygenenum:: rmt_carrier_level_t
-
-Structures
-^^^^^^^^^^
-
-.. doxygenstruct:: rmt_tx_config_t
-    :members:
-
-.. doxygenstruct:: rmt_rx_config_t
-    :members:
-
-.. doxygenstruct:: rmt_config_t
-    :members:
-
-
-Functions
-^^^^^^^^^
-
-.. doxygenfunction:: rmt_set_clk_div
-.. doxygenfunction:: rmt_get_clk_div
-.. doxygenfunction:: rmt_set_rx_idle_thresh
-.. doxygenfunction:: rmt_get_rx_idle_thresh
-.. doxygenfunction:: rmt_set_mem_block_num
-.. doxygenfunction:: rmt_get_mem_block_num
-.. doxygenfunction:: rmt_set_tx_carrier
-.. doxygenfunction:: rmt_set_mem_pd
-.. doxygenfunction:: rmt_get_mem_pd
-.. doxygenfunction:: rmt_tx_start
-.. doxygenfunction:: rmt_tx_stop
-.. doxygenfunction:: rmt_rx_start
-.. doxygenfunction:: rmt_rx_stop
-.. doxygenfunction:: rmt_memory_rw_rst
-.. doxygenfunction:: rmt_set_memory_owner
-.. doxygenfunction:: rmt_get_memory_owner
-.. doxygenfunction:: rmt_set_tx_loop_mode
-.. doxygenfunction:: rmt_get_tx_loop_mode
-.. doxygenfunction:: rmt_set_rx_filter
-.. doxygenfunction:: rmt_set_source_clk
-.. doxygenfunction:: rmt_get_source_clk
-.. doxygenfunction:: rmt_set_idle_level
-.. doxygenfunction:: rmt_get_status
-.. doxygenfunction:: rmt_set_intr_enable_mask
-.. doxygenfunction:: rmt_clr_intr_enable_mask
-.. doxygenfunction:: rmt_set_rx_intr_en
-.. doxygenfunction:: rmt_set_err_intr_en
-.. doxygenfunction:: rmt_set_tx_intr_en
-.. doxygenfunction:: rmt_set_evt_intr_en
-.. doxygenfunction:: rmt_set_pin
-.. doxygenfunction:: rmt_config
-.. doxygenfunction:: rmt_isr_register
-.. doxygenfunction:: rmt_fill_tx_items
-.. doxygenfunction:: rmt_driver_install
-.. doxygenfunction:: rmt_driver_uninstall
-.. doxygenfunction:: rmt_write_items
-.. doxygenfunction:: rmt_wait_tx_done
-.. doxygenfunction:: rmt_get_ringbuf_handler
+.. include:: /_build/inc/rmt.inc
 

docs/api-reference/peripherals/sigmadelta.rst

@@ -15,37 +15,5 @@ Sigma-delta Modulation example: :example:`peripherals/sigmadelta`.
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
-
-  * :component_file:`driver/include/driver/sigmadelta.h`
-
-
-Macros
-^^^^^^
-
-
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-
-Enumerations
-^^^^^^^^^^^^
-
-.. doxygenenum:: sigmadelta_channel_t
-
-Structures
-^^^^^^^^^^
-
-.. doxygenstruct:: sigmadelta_config_t
-    :members:
-
-
-Functions
-^^^^^^^^^
-
-.. doxygenfunction:: sigmadelta_config
-.. doxygenfunction:: sigmadelta_set_duty
-.. doxygenfunction:: sigmadelta_set_prescale
-.. doxygenfunction:: sigmadelta_set_pin
+.. include:: /_build/inc/sigmadelta.inc
 

docs/api-reference/peripherals/spi_master.rst

@@ -109,63 +109,15 @@ Application Example
  
 Display graphics on the ILI9341-based 320x240 LCD: :example:`peripherals/spi_master`.
 
-API Reference
--------------
 
-Header Files
-^^^^^^^^^^^^
+API Reference - SPI Common
+--------------------------
 
-  * :component_file:`driver/include/driver/spi_master.h`
+.. include:: /_build/inc/spi_common.inc
 
-Macros
-^^^^^^
 
-.. doxygendefine:: SPI_DEVICE_TXBIT_LSBFIRST
-.. doxygendefine:: SPI_DEVICE_RXBIT_LSBFIRST
-.. doxygendefine:: SPI_DEVICE_BIT_LSBFIRST
-.. doxygendefine:: SPI_DEVICE_3WIRE
-.. doxygendefine:: SPI_DEVICE_POSITIVE_CS
-.. doxygendefine:: SPI_DEVICE_HALFDUPLEX
-.. doxygendefine:: SPI_DEVICE_CLK_AS_CS
+API Reference - SPI Master
+--------------------------
 
-.. doxygendefine:: SPI_TRANS_MODE_DIO
-.. doxygendefine:: SPI_TRANS_MODE_QIO
-.. doxygendefine:: SPI_TRANS_MODE_DIOQIO_ADDR
-.. doxygendefine:: SPI_TRANS_USE_RXDATA
-.. doxygendefine:: SPI_TRANS_USE_TXDATA
-
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-.. doxygentypedef:: spi_device_handle_t
-
-Enumerations
-^^^^^^^^^^^^
-
-.. doxygenenum:: spi_host_device_t
-
-Structures
-^^^^^^^^^^
-
-.. doxygenstruct:: spi_transaction_t
-  :members:
-
-.. doxygenstruct:: spi_bus_config_t
-  :members:
-
-.. doxygenstruct:: spi_device_interface_config_t
-  :members:
-
-
-
-Functions
----------
-
-.. doxygenfunction:: spi_bus_initialize
-.. doxygenfunction:: spi_bus_free
-.. doxygenfunction:: spi_bus_add_device
-.. doxygenfunction:: spi_bus_remove_device
-.. doxygenfunction:: spi_device_queue_trans
-.. doxygenfunction:: spi_device_get_trans_result
-.. doxygenfunction:: spi_device_transmit
+.. include:: /_build/inc/spi_master.inc
 

docs/api-reference/peripherals/spi_slave.rst

@@ -92,51 +92,5 @@ Slave/master communication: :example:`peripherals/spi_slave`.
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
-
-  * :component_file:`driver/include/driver/spi_slave.h`
-
-Macros
-^^^^^^
-
-.. doxygendefine:: SPI_SLAVE_TXBIT_LSBFIRST
-.. doxygendefine:: SPI_SLAVE_RXBIT_LSBFIRST
-.. doxygendefine:: SPI_SLAVE_BIT_LSBFIRST
-.. doxygendefine:: SPI_SLAVE_POSITIVE_CS
-
-
-
-Enumerations
-^^^^^^^^^^^^
-
-.. doxygenenum:: spi_host_device_t
-
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-Structures
-^^^^^^^^^^
-
-.. doxygenstruct:: spi_slave_transaction_t
-  :members:
-
-.. doxygenstruct:: spi_slave_interface_config_t
-  :members:
-
-.. doxygenstruct:: spi_bus_config_t
-  :members:
-
-Be advised that the slave driver does not use the quadwp/quadhd lines and fields in ``spi_bus_config_t`` refering to these lines
-will be ignored and can thus safely be left uninitialized.
-
-
-Functions
----------
-
-.. doxygenfunction:: spi_slave_initialize
-.. doxygenfunction:: spi_slave_free
-.. doxygenfunction:: spi_slave_queue_trans
-.. doxygenfunction:: spi_slave_get_trans_result
-.. doxygenfunction:: spi_slave_transmit
+.. include:: /_build/inc/spi_slave.inc
 

docs/api-reference/peripherals/timer.rst

@@ -8,7 +8,6 @@ ESP32 chip contains two hardware timer groups, each containing two general-purpo
 
 They are all 64-bit generic timers based on 16-bit prescalers and 64-bit auto-reload-capable up/down counters.
 
-
 Application Example
 -------------------
 
@@ -17,57 +16,5 @@ Application Example
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
-
-  * :component_file:`driver/include/driver/timer.h`
-
-Macros
-^^^^^^
-
-.. doxygendefine:: TIMER_BASE_CLK
-
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-
-Enumerations
-^^^^^^^^^^^^
-
-.. doxygenenum:: timer_group_t
-.. doxygenenum:: timer_idx_t
-.. doxygenenum:: timer_count_dir_t
-.. doxygenenum:: timer_start_t
-.. doxygenenum:: timer_alarm_t
-.. doxygenenum:: timer_intr_mode_t
-.. doxygenenum:: timer_autoreload_t
-
-Structures
-^^^^^^^^^^
-
-.. doxygenstruct:: timer_config_t
-    :members:
-
-
-Functions
-^^^^^^^^^
-
-.. doxygenfunction:: timer_get_counter_value
-.. doxygenfunction:: timer_get_counter_time_sec
-.. doxygenfunction:: timer_set_counter_value
-.. doxygenfunction:: timer_start
-.. doxygenfunction:: timer_pause
-.. doxygenfunction:: timer_set_counter_mode
-.. doxygenfunction:: timer_set_auto_reload
-.. doxygenfunction:: timer_set_divider
-.. doxygenfunction:: timer_set_alarm_value
-.. doxygenfunction:: timer_get_alarm_value
-.. doxygenfunction:: timer_set_alarm
-.. doxygenfunction:: timer_isr_register
-.. doxygenfunction:: timer_init
-.. doxygenfunction:: timer_get_config
-.. doxygenfunction:: timer_group_intr_enable
-.. doxygenfunction:: timer_group_intr_disable
-.. doxygenfunction:: timer_enable_intr
-.. doxygenfunction:: timer_disable_intr
+.. include:: /_build/inc/timer.inc
 

docs/api-reference/peripherals/uart.rst

@@ -16,83 +16,6 @@ Configure uart settings and install uart driver to read/write using UART0 and UA
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
+.. include:: /_build/inc/uart.inc
 
-  * :component_file:`driver/include/driver/uart.h`
-
-Data Structures
-^^^^^^^^^^^^^^^
-
-.. doxygenstruct:: uart_config_t
-   :members:
-
-.. doxygenstruct:: uart_intr_config_t
-   :members:
-
-.. doxygenstruct:: uart_event_t
-   :members:
-
-Macros
-^^^^^^
-
-.. doxygendefine:: UART_FIFO_LEN
-.. doxygendefine:: UART_INTR_MASK
-.. doxygendefine:: UART_LINE_INV_MASK
-.. doxygendefine:: UART_BITRATE_MAX
-.. doxygendefine:: UART_PIN_NO_CHANGE
-.. doxygendefine:: UART_INVERSE_DISABLE
-.. doxygendefine:: UART_INVERSE_RXD
-.. doxygendefine:: UART_INVERSE_CTS
-.. doxygendefine:: UART_INVERSE_TXD
-.. doxygendefine:: UART_INVERSE_RTS
-
-Enumerations
-^^^^^^^^^^^^
-
-.. doxygenenum:: uart_word_length_t
-.. doxygenenum:: uart_stop_bits_t
-.. doxygenenum:: uart_port_t
-.. doxygenenum:: uart_parity_t
-.. doxygenenum:: uart_hw_flowcontrol_t
-.. doxygenenum:: uart_event_type_t
-
-Functions
-^^^^^^^^^
-
-.. doxygenfunction:: uart_set_word_length
-.. doxygenfunction:: uart_get_word_length
-.. doxygenfunction:: uart_set_stop_bits
-.. doxygenfunction:: uart_get_stop_bits
-.. doxygenfunction:: uart_set_parity
-.. doxygenfunction:: uart_get_parity
-.. doxygenfunction:: uart_set_baudrate
-.. doxygenfunction:: uart_get_baudrate
-.. doxygenfunction:: uart_set_line_inverse
-.. doxygenfunction:: uart_set_hw_flow_ctrl
-.. doxygenfunction:: uart_get_hw_flow_ctrl
-.. doxygenfunction:: uart_clear_intr_status
-.. doxygenfunction:: uart_enable_intr_mask
-.. doxygenfunction:: uart_disable_intr_mask
-.. doxygenfunction:: uart_enable_rx_intr
-.. doxygenfunction:: uart_disable_rx_intr
-.. doxygenfunction:: uart_disable_tx_intr
-.. doxygenfunction:: uart_enable_tx_intr
-.. doxygenfunction:: uart_isr_register
-.. doxygenfunction:: uart_set_pin
-.. doxygenfunction:: uart_set_rts
-.. doxygenfunction:: uart_set_dtr
-.. doxygenfunction:: uart_param_config
-.. doxygenfunction:: uart_intr_config
-.. doxygenfunction:: uart_driver_install
-.. doxygenfunction:: uart_driver_delete
-.. doxygenfunction:: uart_wait_tx_done
-.. doxygenfunction:: uart_tx_chars
-.. doxygenfunction:: uart_write_bytes
-.. doxygenfunction:: uart_write_bytes_with_break
-.. doxygenfunction:: uart_read_bytes
-.. doxygenfunction:: uart_flush
-.. doxygenfunction:: uart_get_buffered_data_len
-.. doxygenfunction:: uart_disable_pattern_det_intr
-.. doxygenfunction:: uart_enable_pattern_det_intr
 

docs/api-reference/protocols/mdns.rst

@@ -16,7 +16,9 @@ mDNS Properties
 
 Example method to start mDNS for the STA interface and set ``hostname`` and ``default_instance``:
 
-  ::
+.. highlight:: c
+
+::
 
     mdns_server_t * mdns = NULL;
     
@@ -46,9 +48,7 @@ mDNS can advertise information about network services that your device offers. E
     * ``instance``: friendly name for your service, like ``Jhon's ESP32 Web Server``. If not defined, ``default_instance`` will be used.
     * ``txt``: ``var=val`` array of strings, used to define properties for your service
 
-Example method to add a few services and different properties:
-
-  ::
+Example method to add a few services and different properties::
 
     void add_mdns_services()
     {
@@ -78,13 +78,10 @@ mDNS Query
 ^^^^^^^^^^
 
 mDNS provides methods for browsing for services and resolving host's IP/IPv6 addresses.
-    Results are returned as a linked list of ``mdns_result_t`` objects. If the result is from host query, 
-    it will contain only ``addr`` and ``addrv6`` if found. Service queries will populate all fields 
-    in a result that were found.
 
-Example method to resolve host IPs:
+Results are returned as a linked list of ``mdns_result_t`` objects. If the result is from host query, it will contain only ``addr`` and ``addrv6`` if found. Service queries will populate all fields in a result that were found.
 
-  ::
+Example method to resolve host IPs::
 
     void resolve_mdns_host(const char * hostname)
     {
@@ -110,9 +107,7 @@ Example method to resolve host IPs:
         }
     }
 
-Example method to resolve local services:
-
-  ::
+Example method to resolve local services::
 
     void find_mdns_service(const char * service, const char * proto)
     {
@@ -140,9 +135,7 @@ Example method to resolve local services:
         }
     }
 
-Example of using the methods above:
-
-  ::
+Example of using the methods above::
 
     void my_app_some_method(){
         //search for esp32-mdns.local
@@ -168,48 +161,6 @@ mDNS server/scanner example: :example:`protocols/mdns`.
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
-
-  * :component_file:`mdns/include/mdns.h`
-
-Macros
-^^^^^^
-
-
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-.. doxygentypedef:: mdns_server_t
-.. doxygentypedef:: mdns_result_t
-
-Enumerations
-^^^^^^^^^^^^
-
-
-Structures
-^^^^^^^^^^
+.. include:: /_build/inc/mdns.inc
 
-.. doxygenstruct:: mdns_result_s
-    :members:
-
-
-Functions
-^^^^^^^^^
-
-.. doxygenfunction:: mdns_init
-.. doxygenfunction:: mdns_free
-.. doxygenfunction:: mdns_set_hostname
-.. doxygenfunction:: mdns_set_instance
-.. doxygenfunction:: mdns_service_add
-.. doxygenfunction:: mdns_service_remove
-.. doxygenfunction:: mdns_service_instance_set
-.. doxygenfunction:: mdns_service_txt_set
-.. doxygenfunction:: mdns_service_port_set
-.. doxygenfunction:: mdns_service_remove_all
-.. doxygenfunction:: mdns_query
-.. doxygenfunction:: mdns_query_end
-.. doxygenfunction:: mdns_result_get_count
-.. doxygenfunction:: mdns_result_get
-.. doxygenfunction:: mdns_result_free
 

docs/api-reference/storage/fatfs.rst

@@ -42,10 +42,8 @@ Using FatFs with VFS and SD cards
 ``esp_vfs_fat.h`` header file also provides a convenience function to perform steps 1–3 and 7–9, and also handle SD card initialization: ``esp_vfs_fat_sdmmc_mount``. This function does only limited error handling. Developers are encouraged to look at its source code and incorporate more advanced versions into production applications. ``esp_vfs_fat_sdmmc_unmount`` function unmounts the filesystem and releases resources acquired by ``esp_vfs_fat_sdmmc_mount``.
 
 .. doxygenfunction:: esp_vfs_fat_sdmmc_mount
-
 .. doxygenstruct:: esp_vfs_fat_mount_config_t
     :members:
-
 .. doxygenfunction:: esp_vfs_fat_sdmmc_unmount
 
 FatFS disk IO layer
@@ -56,9 +54,7 @@ FatFs has been extended with an API to register disk IO driver at runtime.
 Implementation of disk IO functions for SD/MMC cards is provided. It can be registered for the given FatFs drive number using ``ff_diskio_register_sdmmc`` function.
 
 .. doxygenfunction:: ff_diskio_register
-
 .. doxygenstruct:: ff_diskio_impl_t
     :members:
-
 .. doxygenfunction:: ff_diskio_register_sdmmc
 

docs/api-reference/storage/index.rst

@@ -5,7 +5,7 @@ Storage API
    :maxdepth: 1
 
    SPI Flash and Partition APIs <spi_flash>
-   SD/MMC <sdmmc>
+   SD/MMC Card Host <sdmmc>
    Non-Volatile Storage <nvs_flash>
    Virtual Filesystem <vfs>
    FAT Filesystem <fatfs>

docs/api-reference/storage/nvs_flash.rst

@@ -26,67 +26,8 @@ Two examples are provided in :example:`storage` directory of ESP-IDF examples:
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
-
-  * :component_file:`nvs_flash/include/nvs_flash.h`
-  * :component_file:`nvs_flash/include/nvs.h`
-
-Macros
-^^^^^^
-
-.. 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
-.. doxygendefine:: ESP_ERR_NVS_NO_FREE_PAGES
-
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-.. doxygentypedef:: nvs_handle
-
-Enumerations
-^^^^^^^^^^^^
-
-.. doxygenenum:: nvs_open_mode
-
-Functions
-^^^^^^^^^
-.. doxygenfunction:: nvs_flash_init
-.. doxygenfunction:: nvs_open
-.. 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
-.. 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
+.. include:: /_build/inc/nvs_flash.inc
+
+.. include:: /_build/inc/nvs.inc
 
 

docs/api-reference/storage/spi_flash.rst

@@ -7,72 +7,6 @@ See also
 - :doc:`Over The Air Update (OTA) API <../system/ota>` provides high-level API for updating app firmware stored in flash.
 - :doc:`Non-Volatile Storage (NVS) API <nvs_flash>` provides a structured API for storing small items of data in SPI flash.
 
-API Reference
--------------
-
-Header Files
-^^^^^^^^^^^^
-
-  * :component_file:`spi_flash/include/esp_spi_flash.h`
-  * :component_file:`spi_flash/include/esp_partition.h`
-  * :component_file:`bootloader_support/include/esp_flash_encrypt.h`
-
-Macros
-^^^^^^
-
-.. doxygendefine:: ESP_ERR_FLASH_BASE
-.. doxygendefine:: ESP_ERR_FLASH_OP_FAIL
-.. doxygendefine:: ESP_ERR_FLASH_OP_TIMEOUT
-.. doxygendefine:: SPI_FLASH_SEC_SIZE
-.. doxygendefine:: SPI_FLASH_MMU_PAGE_SIZE
-.. doxygendefine:: ESP_PARTITION_SUBTYPE_OTA
-.. doxygendefine:: SPI_FLASH_CACHE2PHYS_FAIL
-
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-.. doxygentypedef:: spi_flash_mmap_handle_t
-.. doxygentypedef:: esp_partition_iterator_t
-
-Enumerations
-^^^^^^^^^^^^
-
-.. doxygenenum:: spi_flash_mmap_memory_t
-.. doxygenenum:: esp_partition_type_t
-.. doxygenenum:: esp_partition_subtype_t
-
-Structures
-^^^^^^^^^^
-
-.. doxygenstruct:: esp_partition_t
-
-Functions
-^^^^^^^^^
-
-.. doxygenfunction:: spi_flash_init
-.. doxygenfunction:: spi_flash_get_chip_size
-.. doxygenfunction:: spi_flash_erase_sector
-.. doxygenfunction:: spi_flash_erase_range
-.. doxygenfunction:: spi_flash_write
-.. doxygenfunction:: spi_flash_write_encrypted
-.. doxygenfunction:: spi_flash_read
-.. doxygenfunction:: spi_flash_read_encrypted
-.. doxygenfunction:: spi_flash_mmap
-.. doxygenfunction:: spi_flash_munmap
-.. doxygenfunction:: spi_flash_mmap_dump
-.. doxygenfunction:: spi_flash_cache2phys
-.. doxygenfunction:: spi_flash_phys2cache
-.. doxygenfunction:: spi_flash_cache_enabled
-.. doxygenfunction:: esp_partition_find
-.. doxygenfunction:: esp_partition_find_first
-.. doxygenfunction:: esp_partition_get
-.. doxygenfunction:: esp_partition_next
-.. doxygenfunction:: esp_partition_iterator_release
-.. doxygenfunction:: esp_partition_read
-.. doxygenfunction:: esp_partition_write
-.. doxygenfunction:: esp_partition_erase_range
-.. doxygenfunction:: esp_partition_mmap
-.. doxygenfunction:: esp_flash_encryption_enabled
 
 .. _spi-flash-implementation-details:
 
@@ -108,3 +42,20 @@ Additionally, all API functions are protected with a mutex (s_flash_op_mutex).
 
 In a single core environment (CONFIG_FREERTOS_UNICORE enabled), we simply
 disable both caches, no inter-CPU communication takes place.
+
+API Reference - SPI Flash
+-------------------------
+
+.. include:: /_build/inc/esp_spi_flash.inc
+
+API Reference - Partition Table
+-------------------------------
+
+.. include:: /_build/inc/esp_partition.inc
+
+API Reference - Flash Encrypt
+-----------------------------
+
+.. include:: /_build/inc/esp_flash_encrypt.inc
+
+

docs/api-reference/storage/vfs.rst

@@ -10,38 +10,7 @@ Application Example
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
+.. include:: /_build/inc/esp_vfs.inc
 
-  * :component_file:`vfs/include/esp_vfs.h`
-  * :component_file:`vfs/include/esp_vfs_dev.h`
+.. include:: /_build/inc/esp_vfs_dev.inc
 
-Macros
-^^^^^^
-
-.. doxygendefine:: ESP_VFS_PATH_MAX
-.. doxygendefine:: ESP_VFS_FLAG_DEFAULT
-.. doxygendefine:: ESP_VFS_FLAG_CONTEXT_PTR
-
-Structures
-^^^^^^^^^^
-
-.. doxygenstruct:: esp_vfs_t
-   :members:
-
-Functions
-^^^^^^^^^
-
-.. doxygenfunction:: esp_vfs_register
-.. doxygenfunction:: esp_vfs_unregister
-.. doxygenfunction:: esp_vfs_write
-.. doxygenfunction:: esp_vfs_lseek
-.. doxygenfunction:: esp_vfs_read
-.. doxygenfunction:: esp_vfs_open
-.. doxygenfunction:: esp_vfs_close
-.. doxygenfunction:: esp_vfs_fstat
-.. doxygenfunction:: esp_vfs_stat
-.. doxygenfunction:: esp_vfs_link
-.. doxygenfunction:: esp_vfs_unlink
-.. doxygenfunction:: esp_vfs_rename
-.. doxygenfunction:: esp_vfs_dev_uart_register

docs/api-reference/storage/wear-levelling.rst

@@ -6,12 +6,10 @@ See also
 - :doc:`FAT Filesystem <../../api-guides/partition-tables>`
 - :doc:`Partition Table documentation <../../api-guides/partition-tables>`
 
-
 Application Example
 -------------------
 
-An example which combines wear levelling driver with FATFS library is provided in ``examples/storage/wear_levelling`` directory. This example initializes the 
-wear levelling driver, mounts FATFS partition, and 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 wear levelling driver with FATFS library is provided in ``examples/storage/wear_levelling`` directory. This example initializes the wear levelling driver, mounts FATFS partition, and writes and reads data from it using POSIX and C library APIs. See README.md file in the example directory for more information.
 
 High level API Reference
 ------------------------
@@ -19,7 +17,7 @@ High level API Reference
 Header Files
 ^^^^^^^^^^^^
 
-  * :component_file:`fatfs/src/esp_vfs_fat.h`
+* :component_file:`fatfs/src/esp_vfs_fat.h`
 
 Functions
 ^^^^^^^^^
@@ -32,19 +30,5 @@ Functions
 Mid level API Reference
 -----------------------
 
-Header Files
-^^^^^^^^^^^^
-
-  * :component_file:`wear_levelling/include/wear_levelling.h`
-
-Functions
-^^^^^^^^^
-
-.. doxygenfunction:: wl_mount
-.. doxygenfunction:: wl_unmount
-.. doxygenfunction:: wl_erase_range
-.. doxygenfunction:: wl_write
-.. doxygenfunction:: wl_read
-.. doxygenfunction:: wl_size
-.. doxygenfunction:: wl_sector_size
+.. include:: /_build/inc/wear_levelling.inc
 

docs/api-reference/system/base_mac_address.rst

@@ -4,7 +4,7 @@ Base MAC address
 Overview
 --------
 
-Serveral universally administered(by IEEE) MAC addresses are uniquely assigned to the networking interfaces(WiFi/BT/Ethernet). 
+Serveral MAC addresses (universally administered by IEEE) are uniquely assigned to the networking interfaces (WiFi/BT/Ethernet). 
 The final octet of each universally administered MAC address increases by one. Only the first one which is called base MAC address 
 of them is stored in EFUSE or external storage, the others are generated from it. Here, 'generate' means adding 0, 1, 2 and 3 
 (respectively) to the final octet of the base MAC address. 
@@ -12,7 +12,7 @@ of them is stored in EFUSE or external storage, the others are generated from it
 If the universally administered MAC addresses are not enough for all of the networking interfaces. Local administered MAC addresses
 which are derived from universally administered MAC addresses are assigned to the reset of networking interfaces. 
 
-A `definition of local vs universal MAC address can be found on Wikipedia<https://en.wikipedia.org/wiki/MAC_address#Universal_vs._local>`.
+A `definition of local vs universal MAC address can be found on Wikipedia <https://en.wikipedia.org/wiki/MAC_address#Universal_vs._local>`_.
 
 The number of universally administered MAC address can be configured using ``make menuconfig``.
 
@@ -21,30 +21,35 @@ Base MAC address
 
 If using the default base MAC address factory programmed by Espressif in BLK0 of EFUSE, nothing needs to be done.
 
-If using a custom base MAC address stored in BLK3 of EFUSE, call API esp_efuse_mac_get_custom() to get the base MAC address
-which is stored in BLK3 of EFUSE. If correct MAC address is returned, then call esp_base_mac_addr_set() to set the base MAC 
+If using a custom base MAC address stored in BLK3 of EFUSE, call API ``esp_efuse_mac_get_custom()`` to get the base MAC address
+which is stored in BLK3 of EFUSE. If correct MAC address is returned, then call ``esp_base_mac_addr_set()`` to set the base MAC 
 address for system to generate the MAC addresses used by the networking interfaces(WiFi/BT/Ethernet).
 There are 192 bits storage spaces for custom to store base MAC address in BLK3 of EFUSE. They are EFUSE_BLK3_RDATA0, 
 EFUSE_BLK3_RDATA1, EFUSE_BLK3_RDATA2, EFUSE_BLK3_RDATA3, EFUSE_BLK3_RDATA4 and EFUSE_BLK3_RDATA5, each of them is 32 bits 
 register. The format of the 192 bits storage spaces is:
-------------------------------------------------------
-Field       |Bits |Range     |Description
-------------------------------------------------------
-version     |8    |[191:184] |1: useful. 0: useless
-------------------------------------------------------
-reserve     |112  |[183:72]  |reserved
-------------------------------------------------------
-mac address |64   |[71:8]    |base MAC address
-------------------------------------------------------
-mac crc     |8    |[7:0]     |crc of base MAC address
-------------------------------------------------------
+
+.. highlight:: none
+
+::
+
+    ------------------------------------------------------
+    Field       |Bits |Range     |Description
+    ------------------------------------------------------
+    version     |8    |[191:184] |1: useful. 0: useless
+    ------------------------------------------------------
+    reserve     |112  |[183:72]  |reserved
+    ------------------------------------------------------
+    mac address |64   |[71:8]    |base MAC address
+    ------------------------------------------------------
+    mac crc     |8    |[7:0]     |crc of base MAC address
+    ------------------------------------------------------
 
 If using base MAC address stored in external storage, firstly get the base MAC address stored in external storage, then call 
-API esp_base_mac_addr_set() to set the base MAC address for system to generate the MAC addresses used by the networking 
+API ``esp_base_mac_addr_set()`` to set the base MAC address for system to generate the MAC addresses used by the networking 
 interfaces(WiFi/BT/Ethernet).
 
 All of the steps must be done before initializing the networking interfaces(WiFi/BT/Ethernet). It is recommended to do it in 
-app_main() which can be referenced in example `system/base_mac_address`.
+``app_main()`` which can be referenced in :example:`system/base_mac_address`.
 
 Number of universally administered MAC address
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -74,4 +79,4 @@ Functions
 ---------
 
 .. doxygenfunction:: esp_base_mac_addr_set
-.. doxygenfunction:: esp_efuse_mac_get_custom
+.. doxygenfunction:: esp_efuse_mac_get_custom

docs/api-reference/system/intr_alloc.rst

@@ -83,46 +83,9 @@ It can also be useful to keep an interrupt handler in IRAM if it is called very
 
 Refer to the :ref:`SPI flash API documentation <iram-safe-interrupt-handlers>` for more details.
 
-Application Example
--------------------
-
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
-
-  * :component_file:`esp32/include/esp_intr_alloc.h`
-
-
-Macros
-^^^^^^
-
-.. doxygendefine:: ESP_INTR_FLAG_LEVEL1
-.. doxygendefine:: ESP_INTR_FLAG_LEVEL2
-.. doxygendefine:: ESP_INTR_FLAG_LEVEL3
-.. doxygendefine:: ESP_INTR_FLAG_LEVEL4
-.. doxygendefine:: ESP_INTR_FLAG_LEVEL5
-.. doxygendefine:: ESP_INTR_FLAG_LEVEL6
-.. doxygendefine:: ESP_INTR_FLAG_NMI
-.. doxygendefine:: ESP_INTR_FLAG_LOWMED
-.. doxygendefine:: ESP_INTR_FLAG_HIGH
-.. doxygendefine:: ESP_INTR_FLAG_SHARED
-.. doxygendefine:: ESP_INTR_FLAG_EDGE
-.. doxygendefine:: ESP_INTR_FLAG_IRAM
-.. doxygendefine:: ESP_INTR_FLAG_INTRDISABLED
-
-Functions
-^^^^^^^^^
-
-.. doxygenfunction:: esp_intr_mark_shared
-.. doxygenfunction:: esp_intr_reserve
-.. doxygenfunction:: esp_intr_alloc
-.. doxygenfunction:: esp_intr_alloc_intrstatus
-.. doxygenfunction:: esp_intr_free
-.. doxygenfunction:: esp_intr_get_cpu
-.. doxygenfunction:: esp_intr_get_intno
-.. doxygenfunction:: esp_intr_disable
-.. doxygenfunction:: esp_intr_enable
-.. doxygenfunction:: esp_intr_noniram_disable
-.. doxygenfunction:: esp_intr_noniram_enable
+.. include:: /_build/inc/esp_intr_alloc.inc
+
+

docs/api-reference/system/log.rst

@@ -12,57 +12,7 @@ Log library is commonly used by most of esp-idf components and examples. For dem
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
-
-  * :component_file:`log/include/esp_log.h`
-
-Macros
-^^^^^^
-
-.. doxygendefine:: LOG_COLOR_E
-.. doxygendefine:: LOG_COLOR_W
-.. doxygendefine:: LOG_COLOR_I
-.. doxygendefine:: LOG_COLOR_D
-.. doxygendefine:: LOG_COLOR_V
-.. doxygendefine:: LOG_RESET_COLOR
-.. doxygendefine:: LOG_FORMAT
-.. doxygendefine:: LOG_LOCAL_LEVEL
-.. doxygendefine:: ESP_EARLY_LOGE
-.. doxygendefine:: ESP_EARLY_LOGW
-.. doxygendefine:: ESP_EARLY_LOGI
-.. doxygendefine:: ESP_EARLY_LOGD
-.. doxygendefine:: ESP_EARLY_LOGV
-.. doxygendefine:: ESP_LOGE
-.. doxygendefine:: ESP_LOGW
-.. doxygendefine:: ESP_LOGI
-.. doxygendefine:: ESP_LOGD
-.. doxygendefine:: ESP_LOGV
-
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-.. doxygentypedef:: vprintf_like_t
-
-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
-
-
-
-
-
-
-
+.. include:: /_build/inc/esp_log.inc
 
 
 

docs/api-reference/system/mem_alloc.rst

@@ -1,5 +1,5 @@
 Memory allocation
-====================
+=================
 
 Overview
 --------
@@ -30,48 +30,13 @@ If a certain memory structure is only addressed in 32-bit units, for example an
 useful to allocate it with the MALLOC_CAP_32BIT flag. This also allows the allocator to give out IRAM memory; something
 which it can't do for a normal malloc() call. This can help to use all the available memory in the ESP32.
 
+API Reference - Heap Allocation
+-------------------------------
 
-API Reference
--------------
+.. include:: /_build/inc/esp_heap_alloc_caps.inc
 
-Header Files
-^^^^^^^^^^^^
+API Reference - Heap Regions
+----------------------------
 
-  * :component_file:`esp32/include/esp_heap_alloc_caps.h`
-  * :component_file:`freertos/include/freertos/heap_regions.h`
+.. include:: /_build/inc/heap_regions.inc
 
-
-Macros
-^^^^^^
-
-.. doxygendefine:: MALLOC_CAP_EXEC
-.. doxygendefine:: MALLOC_CAP_32BIT
-.. doxygendefine:: MALLOC_CAP_8BIT
-.. doxygendefine:: MALLOC_CAP_DMA
-.. doxygendefine:: MALLOC_CAP_PID2
-.. doxygendefine:: MALLOC_CAP_PID3
-.. doxygendefine:: MALLOC_CAP_PID4
-.. doxygendefine:: MALLOC_CAP_PID5
-.. doxygendefine:: MALLOC_CAP_PID6
-.. doxygendefine:: MALLOC_CAP_PID7
-.. doxygendefine:: MALLOC_CAP_SPISRAM
-.. doxygendefine:: MALLOC_CAP_INVALID
-
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-.. doxygentypedef:: HeapRegionTagged_t
-
-
-Functions
-^^^^^^^^^
-
-.. doxygenfunction:: heap_alloc_caps_init
-.. doxygenfunction:: pvPortMallocCaps
-.. doxygenfunction:: xPortGetFreeHeapSizeCaps
-.. doxygenfunction:: xPortGetMinimumEverFreeHeapSizeCaps
-.. doxygenfunction:: vPortDefineHeapRegionsTagged
-.. doxygenfunction:: pvPortMallocTagged
-.. doxygenfunction:: vPortFreeTagged
-.. doxygenfunction:: xPortGetMinimumEverFreeHeapSizeTagged
-.. doxygenfunction:: xPortGetFreeHeapSizeTagged

docs/api-reference/system/ota.rst

@@ -2,7 +2,7 @@ Over The Air Updates (OTA)
 ==========================
 
 OTA Process Overview
-^^^^^^^^^^^^^^^^^^^^
+--------------------
 
 The OTA update mechanism allows a device to update itself based on data received while the normal firmware is running
 (for example, over WiFi or Bluetooth.)
@@ -17,7 +17,7 @@ next boot.
 .. _ota_data_partition:
 
 OTA Data Partition
-^^^^^^^^^^^^^^^^^^
+------------------
 
 An OTA data partition (type ``data``, subtype ``ota``) must be included in the :doc:`Partition Table <../../api-guides/partition-tables>`
 of any project which uses the OTA functions.
@@ -46,32 +46,7 @@ End-to-end example of OTA firmware update workflow: :example:`system/ota`.
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
+.. include:: /_build/inc/esp_ota_ops.inc
 
-  * :component_file:`app_update/include/esp_ota_ops.h`
 
-Macros
-^^^^^^
 
-.. doxygendefine:: ESP_ERR_OTA_BASE
-.. doxygendefine:: ESP_ERR_OTA_PARTITION_CONFLICT
-.. doxygendefine:: ESP_ERR_OTA_SELECT_INFO_INVALID
-.. doxygendefine:: ESP_ERR_OTA_VALIDATE_FAILED
-.. doxygendefine:: OTA_SIZE_UNKNOWN
-
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-.. doxygentypedef:: esp_ota_handle_t
-
-Functions
-^^^^^^^^^
-
-.. doxygenfunction:: esp_ota_begin
-.. doxygenfunction:: esp_ota_write
-.. doxygenfunction:: esp_ota_end
-.. doxygenfunction:: esp_ota_get_running_partition
-.. doxygenfunction:: esp_ota_set_boot_partition
-.. doxygenfunction:: esp_ota_get_boot_partition
-.. doxygenfunction:: esp_ota_get_next_update_partition

docs/api-reference/template.rst

@@ -3,113 +3,103 @@ API Documentation Template
 
 .. note::
 
-   *INSTRUCTIONS*
+    *INSTRUCTIONS*
 
-   1. Use this file as a template to document API.
-   2. Change the file name to the name of the header file that represents documented API.
-   3. Include respective files with descriptions from the API folder using ``..include::``
 
-     * README.rst
-     * example.rst
 
-   4. Optionally provide description right in this file.
-   5. Once done, remove all instructions like this one and any superfluous headers.
+    1. Use this file (:idf_file:`docs/api-reference/template.rst`) as a template to document API.
+    2. Change the file name to the name of the header file that represents documented API.
+    3. Include respective files with descriptions from the API folder using ``..include::``
+
+        * README.rst
+        * example.rst
+        * ...
+
+    4. Optionally provide description right in this file.
+    5. Once done, remove all instructions like this one and any superfluous headers.
 
 Overview
 --------
 
 .. note::
 
-   *INSTRUCTIONS*
+    *INSTRUCTIONS*
 
-   1. Provide overview where and how this API may be used. 
-   2. Where applicable include code snippets to illustrate functionality of particular functions.
-   3. To distinguish between sections, use the following `heading levels <http://www.sphinx-doc.org/en/stable/rest.html#sections>`_:
+    1. Provide overview where and how this API may be used. 
+    2. Where applicable include code snippets to illustrate functionality of particular functions.
+    3. To distinguish between sections, use the following `heading levels <http://www.sphinx-doc.org/en/stable/rest.html#sections>`_:
 
-     * ``#`` with overline, for parts
-     * ``*`` with overline, for chapters
-     * ``=``, for sections
-     * ``-``, for subsections
-     * ``^``, for subsubsections
-     * ``"``, for paragraphs
+        * ``#`` with overline, for parts
+        * ``*`` with overline, for chapters
+        * ``=``, for sections
+        * ``-``, for subsections
+        * ``^``, for subsubsections
+        * ``"``, for paragraphs
 
 Application Example
 -------------------
 
 .. note::
 
-   *INSTRUCTIONS*
+    *INSTRUCTIONS*
 
-   1. Prepare one or more practical examples to demonstrate functionality of this API.
-   2. Each example should follow pattern of projects located in ``esp-idf/examples/`` folder.
-   3. Place example in this folder complete with ``README.md`` file.
-   4. Provide overview of demonstrated functionality in ``README.md``.
-   5. With good overview reader should be able to understand what example does without opening the source code.
-   6. Depending on complexity of example, break down description of code into parts and provide overview of functionality of each part.
-   7. Include flow diagram and screenshots of application output if applicable.
-   8. Finally add in this section synopsis of each example together with link to respective folder in ``esp-idf/examples/``.
+    1. Prepare one or more practical examples to demonstrate functionality of this API.
+    2. Each example should follow pattern of projects located in ``esp-idf/examples/`` folder.
+    3. Place example in this folder complete with ``README.md`` file.
+    4. Provide overview of demonstrated functionality in ``README.md``.
+    5. With good overview reader should be able to understand what example does without opening the source code.
+    6. Depending on complexity of example, break down description of code into parts and provide overview of functionality of each part.
+    7. Include flow diagram and screenshots of application output if applicable.
+    8. Finally add in this section synopsis of each example together with link to respective folder in ``esp-idf/examples/``.
   
 API Reference
 -------------
 
-.. note::
-
-   *INSTRUCTIONS*
- 
-   1. Specify the names of header files used to generate this reference. Each name should be linked to the source on `espressif/esp-idf <https://github.com/espressif/esp-idf>`_ repository.
-   2. Provide list of API members divided into sections. 
-   3. Use corresponding ``.. doxygen..`` directives, so member documentation is auto updated.
-
-     * Data Structures -``.. doxygenstruct::`` together with ``:members:``
-     * Macros - ``.. doxygendefine::``
-     * Type Definitions - ``.. doxygentypedef::``
-     * Enumerations - ``.. doxygenenum::``
-     * Functions - ``.. doxygenfunction::``
-
-     See `Breathe documentation <https://breathe.readthedocs.io/en/latest/directives.html>`_ for additional information. 
+.. highlight:: none
 
-   4. Once done remove superfluous headers.
-   5. When changes are committed and documentation is build, check how this section rendered. :doc:`Correct annotations <../contribute/documenting-code>` in respective header files, if required.
-
-Header Files
-^^^^^^^^^^^^
-
-  * `path/header-file.h`
-
-Data Structures
-^^^^^^^^^^^^^^^
-
-::
+.. note::
 
-  .. doxygenstruct:: name_of_structure
-     :members:
+    *INSTRUCTIONS*
 
-Macros
-^^^^^^
+    1. This repository provides for automatic update of API reference documentation using :doc:`code markup retrieved by Doxygen from header files <../contribute/documenting-code>`.
+    
+    2. Update is done on each documentation build by invoking script :idf_file:`docs/gen-dxd.py` for all header files listed in the ``INPUT`` statement of :idf_file:`docs/Doxyfile`. 
+    
+    3. Each line of the ``INPUT`` statement  (other than a comment that begins with ``##``) contains a path to header file ``*.h`` that will be used to generate corresponding ``*.inc`` files::
 
-::
+        ##
+        ## Wi-Fi - API Reference
+        ##
+        ../components/esp32/include/esp_wifi.h \
+        ../components/esp32/include/esp_smartconfig.h \
 
-  .. doxygendefine:: name_of_macro
+    4. The ``*.inc`` files contain formatted reference of API members generated automatically on each documentation build. All ``*.inc`` files are placed in Sphinx ``_build`` directory. To see directives generated for e.g. ``esp_wifi.h``, run ``python gen-dxd.py esp32/include/esp_wifi.h``.
 
-Type Definitions
-^^^^^^^^^^^^^^^^
+    5. To show contents of ``*.inc`` file in documentation, include it as follows::
 
-::
+       .. include:: /_build/inc/esp_wifi.inc
 
-  .. doxygentypedef:: name_of_type
+       For example see :idf_file:`docs/api-reference/wifi/esp_wifi.rst`
+    
+    6. Optionally, rather that using ``*.inc`` files, you may want to describe API in you own way. See :idf_file:`docs/api-reference/system/deep_sleep.rst` for example.
 
-Enumerations
-^^^^^^^^^^^^
+       Below is the list of common ``.. doxygen...::`` directives:
 
-::
+        * Functions - ``.. doxygenfunction:: name_of_function``
+        * Unions -``.. doxygenunion:: name_of_union``
+        * Structures -``.. doxygenstruct:: name_of_structure`` together with ``:members:``
+        * Macros - ``.. doxygendefine:: name_of_define``
+        * Type Definitions - ``.. doxygentypedef:: name_of_type``
+        * Enumerations - ``.. doxygenenum:: name_of_enumeration``
 
-  .. doxygenenum:: name_of_enumeration
+       See `Breathe documentation <https://breathe.readthedocs.io/en/latest/directives.html>`_ for additional information.
 
-Functions
-^^^^^^^^^
+       To provide a link to header file, use the :ref:`link custom role <link-custom-roles>` as follows::
 
-::
+       * :component_file:`path_to/header_file.h`
 
-  .. doxygenfunction:: name_of_function
+    7. In any case, to generate API reference, the file :idf_file:`docs/Doxyfile` should be updated with paths to ``*.h`` headers that are being documented.
+    
+    8. When changes are committed and documentation is build, check how this section has been rendered. :doc:`Correct annotations <../contribute/documenting-code>` in respective header files, if required.
 
 

docs/api-reference/wifi/esp_smartconfig.rst

@@ -4,22 +4,4 @@ Smart Config
 API Reference
 -------------
 
-Header Files
-^^^^^^^^^^^^
-
-  * :component_file:`esp32/include/esp_smartconfig.h`
-
-Type Definitions
-^^^^^^^^^^^^^^^^
-
-.. doxygentypedef:: sc_callback_t
-
-Functions
-^^^^^^^^^
-
-.. doxygenfunction:: esp_smartconfig_get_version
-.. doxygenfunction:: esp_smartconfig_start
-.. doxygenfunction:: esp_smartconfig_stop
-.. doxygenfunction:: esp_esptouch_set_timeout
-.. doxygenfunction:: esp_smartconfig_set_type
-.. doxygenfunction:: esp_smartconfig_fast_mode
+.. include:: /_build/inc/esp_smartconfig.inc

docs/api-reference/wifi/esp_wifi.rst

@@ -8,71 +8,18 @@ Overview
 
 .. _Instructions: ../template.html
 
-Application Example
--------------------
+Application Examples
+--------------------
 
-Simple code showing how to connect ESP32 module to an Access Point: `esp-idf-template <https://github.com/espressif/esp-idf-template>`_.
+See :example:`wifi` directory of ESP-IDF examples that contains the following applications:
 
-API Reference
--------------
-
-Header Files
-^^^^^^^^^^^^
-
-  * :component_file:`esp32/include/esp_wifi.h`
-
-Macros
-------
+* Simple application showing how to connect ESP32 module to an Access Point - `esp-idf-template <https://github.com/espressif/esp-idf-template>`_.
 
-.. doxygendefine:: WIFI_INIT_CONFIG_DEFAULT
+* Using power save mode of Wi-Fi - :example:`wifi/power_save`.
 
 
-Type Definitions
-----------------
-
-.. doxygentypedef:: wifi_promiscuous_cb_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_deauth_sta
-.. doxygenfunction:: esp_wifi_scan_start
-.. doxygenfunction:: esp_wifi_scan_stop
-.. doxygenfunction:: esp_wifi_scan_get_ap_num
-.. doxygenfunction:: esp_wifi_scan_get_ap_records
-.. doxygenfunction:: esp_wifi_sta_get_ap_info
-.. 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_ap_get_sta_list
-.. doxygenfunction:: esp_wifi_set_storage
-.. 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
+API Reference
+-------------
 
+.. include:: /_build/inc/esp_wifi.inc
 

docs/conf.py

@@ -12,8 +12,7 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys
-import os
+import sys, os
 import re
 from subprocess import call, Popen, PIPE
 import shlex
@@ -24,10 +23,16 @@ import shlex
 sys.path.insert(0, os.path.abspath('.'))
 
 from repo_util import run_cmd_get_output
-# -- Run DoxyGen to prepare XML for Sphinx---------------------------------
-# ref. https://github.com/rtfd/readthedocs.org/issues/388
 
+# Call Doxygen to get XML files from the header files
+print "Calling Doxygen to generate latest XML files"
 call('doxygen')
+# Generate 'api_name.inc' files using the XML files by Doxygen
+os.system("python gen-dxd.py")
+
+# http://stackoverflow.com/questions/12772927/specifying-an-online-image-in-sphinx-restructuredtext-format
+# 
+suppress_warnings = ['image.nonlocal_uri']
 
 # -- General configuration ------------------------------------------------
 
@@ -290,3 +295,4 @@ if not on_rtd:  # only import and set the theme if we're building docs locally
     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # otherwise, readthedocs.org uses their theme by default, so no need to specify it
+

docs/contribute/documenting-code.rst

@@ -95,7 +95,7 @@ There is couple of tips, how you can make your documentation even better and mor
     * @endcode
     *
 
-    The code snippet should be enclosed in a comment block of the function that it illustrates.
+   The code snippet should be enclosed in a comment block of the function that it illustrates.
 
 2. To highlight some important information use command ``@attention`` or ``@note``. ::
 
@@ -105,9 +105,24 @@ There is couple of tips, how you can make your documentation even better and mor
     *     2. If the ESP32 is connected to an AP, call esp_wifi_disconnect to disconnect.
     *
 
-  Above example also shows how to use a numbered list.
+   Above example also shows how to use a numbered list.
 
-3. Use markdown to make your documentation even more readable. You will add headers, links, tables and more. ::
+3. To provide common description to a group of similar functions, enclose them using ``/**@{*/`` and ``/**@}*/`` markup commands::
+
+    /**@{*/
+    /**
+     * @brief common description of similar functions
+     *
+     */
+    void  first_similar_function (void);
+    void second_similar_function (void);
+    /**@}*/ 
+
+   For practical example see :component_file:`nvs_flash/include/nvs.h`.
+
+4. You may want to go even further and skip some code like e.g. repetitive defines or enumerations. In such case enclose the code within ``/** @cond */`` and ``/** @endcond */`` commands. Example of such implementation is provided in :component_file:`driver/include/driver/gpio.h`.
+
+5. Use markdown to make your documentation even more readable. You will add headers, links, tables and more. ::
 
     *
     * [ESP32 Technical Reference](http://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf)
@@ -117,8 +132,9 @@ There is couple of tips, how you can make your documentation even better and mor
 
     Code snippets, notes, links, etc. will not make it to the documentation, if not enclosed in a comment block associated with one of documented objects.
 
-4. Prepare one or more complete code examples together with description. Place description in a separate file ``README.md`` in specific folder of :idf:`examples` directory. 
+6. Prepare one or more complete code examples together with description. Place description in a separate file ``README.md`` in specific folder of :idf:`examples` directory. 
 
+.. _link-custom-roles:
 
 Linking Examples
 ----------------
@@ -128,13 +144,13 @@ When linking to examples on GitHub do not use absolute / hadcoded URLs. Instead,
 The following roles are provided:
 
 - ``:idf:`path``` - points to directory inside ESP-IDF
-- ``:idf_blob:`path``` - points to file inside ESP-IDF
+- ``:idf_file:`path``` - points to file inside ESP-IDF
 - ``:idf_raw:`path``` - points to raw view of the file inside ESP-IDF
 - ``:component:`path``` - points to directory inside ESP-IDF components dir
-- ``:component_blob:`path``` - points to file inside ESP-IDF components dir
+- ``:component_file:`path``` - points to file inside ESP-IDF components dir
 - ``:component_raw:`path``` - points to raw view of the file inside ESP-IDF components dir
 - ``:example:`path``` - points to directory inside ESP-IDF examples dir
-- ``:example_blob:`path``` - points to file inside ESP-IDF examples dir
+- ``:example_file:`path``` - points to file inside ESP-IDF examples dir
 - ``:example_raw:`path``` - points to raw view of the file inside ESP-IDF examples dir
 
 A check is added to the CI build script, which searches RST files for presence of hard-coded links (identified by tree/master, blob/master, or raw/master part of the URL). This check can be run manually: ``cd docs`` and then ``make gh-linkcheck``.
@@ -170,4 +186,12 @@ We love it even better, if it is well documented, so we can quickly make it run
 
 Go ahead, contribute your code and documentation!
 
+
+Related Documents
+-----------------
+
+* :doc:`../api-reference/template`
+
+
 .. _espressif/esp-idf: https://github.com/espressif/esp-idf/
+

docs/doxygen_xml_to_rst.xslt

@@ -1,58 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-
-<!-- This XSL transform converts Doxygen XML output for a header file into Sphinx/Breathe compatible list of APIs -->
-<!-- Usage:  xsltproc doxygen_xml_to_rst.xslt xml/esp__xxxx_8h.xml -->
-
-<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
-    <xsl:output method="text" encoding="UTF-8"/>
-    <xsl:template match="/">
-        <xsl:text>Macros&#xA;</xsl:text>
-        <xsl:text>^^^^^^&#xA;&#xA;</xsl:text>
-        <xsl:for-each select="doxygen/compounddef/sectiondef/memberdef[@kind='define']">
-            <xsl:text>.. doxygendefine:: </xsl:text>
-            <xsl:value-of select="name"/>
-            <xsl:text>&#xA;</xsl:text>
-        </xsl:for-each>
-        <xsl:text>&#xA;</xsl:text>
-
-        <xsl:text>Type Definitions&#xA;</xsl:text>
-        <xsl:text>^^^^^^^^^^^^^^^^&#xA;&#xA;</xsl:text>
-        <xsl:for-each select="doxygen/compounddef/sectiondef/memberdef[@kind='typedef']">
-            <xsl:text>.. doxygentypedef:: </xsl:text>
-            <xsl:value-of select="name"/>
-            <xsl:text>&#xA;</xsl:text>
-        </xsl:for-each>
-        <xsl:text>&#xA;</xsl:text>
-
-        <xsl:text>Enumerations&#xA;</xsl:text>
-        <xsl:text>^^^^^^^^^^^^&#xA;&#xA;</xsl:text>
-        <xsl:for-each select="doxygen/compounddef/sectiondef/memberdef[@kind='enum']">
-            <xsl:text>.. doxygenenum:: </xsl:text>
-            <xsl:value-of select="name"/>
-            <xsl:text>&#xA;</xsl:text>
-        </xsl:for-each>
-        <xsl:text>&#xA;</xsl:text>
-
-        <!-- TODO: figure out why structures are listed as innerclass instances -->
-        <xsl:text>Structures&#xA;</xsl:text>
-        <xsl:text>^^^^^^^^^^&#xA;&#xA;</xsl:text>
-        <xsl:for-each select="doxygen/compounddef/innerclass">
-            <xsl:text>.. doxygenstruct:: </xsl:text>
-            <xsl:value-of select="."/>
-            <xsl:text>&#xA;</xsl:text>
-            <xsl:text>    :members:&#xA;</xsl:text>
-            <xsl:text>&#xA;</xsl:text>
-        </xsl:for-each>
-        <xsl:text>&#xA;</xsl:text>
-
-        <xsl:text>Functions&#xA;</xsl:text>
-        <xsl:text>^^^^^^^^^&#xA;&#xA;</xsl:text>
-        <xsl:for-each select="doxygen/compounddef/sectiondef/memberdef[@kind='function']">
-            <xsl:text>.. doxygenfunction:: </xsl:text>
-            <xsl:value-of select="name"/>
-            <xsl:text>&#xA;</xsl:text>
-        </xsl:for-each>
-        <xsl:text>&#xA;</xsl:text>
-
-    </xsl:template>
-</xsl:stylesheet>

docs/gen-dxd.py

@@ -0,0 +1,301 @@
+# gen-dxd.py - Generate Doxygen Directives
+#
+# This code is in the Public Domain (or CC0 licensed, at your option.)
+# Unless required by applicable law or agreed to in writing, this
+# software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+# CONDITIONS OF ANY KIND, either express or implied.
+#
+
+import sys
+import os
+import re
+
+# Script configuration
+header_file_path_prefix = "../components/"
+"""string: path prefix for header files.
+"""
+doxyfile_path = "Doxyfile"
+"""string: path to a file containing header files to processs.
+"""
+xml_directory_path = "xml"
+"""string: path to directory with XML files by Doxygen.
+"""
+inc_directory_path = "_build/inc"
+"""string: path prefix for header files.
+"""
+all_kinds = [
+    ("function", "Functions"),
+    ("union", "Unions"),
+    ("struct", "Structures"),
+    ("define", "Macros"),
+    ("typedef", "Type Definitions"),
+    ("enum", "Enumerations")
+    ]
+"""list of items that will be generated for a single API file
+"""
+
+
+def get_doxyfile_input():
+    """Get contents of Doxyfile's INPUT statement.
+
+    Returns:
+        Contents of Doxyfile's INPUT.
+
+    """
+    if not os.path.isfile(doxyfile_path):
+        print "Doxyfile '%s' does not exist!" % doxyfile_path
+        sys.exit()
+
+    print "Getting Doxyfile's INPUT"
+
+    input_file = open(doxyfile_path, "r")
+
+    line = input_file.readline()
+    # read contents of Doxyfile until 'INPUT' statement
+    while line:
+        if line.find("INPUT") == 0:
+            break
+        line = input_file.readline()
+
+    doxyfile_INPUT = ""
+    line = input_file.readline()
+    # skip input_file contents until end of 'INPUT' statement
+    while line:
+        if line.isspace():
+            # we have reached the end of 'INPUT' statement
+            break
+        # process only lines that are not comments
+        if line.find("#") == -1:
+            # extract header file path inside components folder
+            m = re.search(header_file_path_prefix + "(.*\.h)", line)
+            header_file_path = m.group(1)
+            doxyfile_INPUT += header_file_path + "\n"
+        # proceed reading next line
+        line = input_file.readline()
+
+    input_file.close()
+    return doxyfile_INPUT
+
+
+def get_api_name(header_file_path):
+    """Get name of API from header file path.
+
+    Args:
+        header_file_path: path to the header file.
+
+    Returns:
+        The name of API.
+
+    """
+    api_name = ""
+    regex = r".*/(.*)\.h"
+    m = re.search(regex, header_file_path)
+    if m:
+        api_name = m.group(1)
+
+    return api_name
+
+
+def get_rst_header(header_name):
+    """Get rst formatted code with a header.
+
+    Args:
+        header_name: name of header.
+
+    Returns:
+        Formatted rst code with the header.
+
+    """
+
+    rst_output = ""
+    rst_output += header_name + "\n"
+    rst_output += "^" * len(header_name) + "\n"
+    rst_output += "\n"
+
+    return rst_output
+
+
+def select_unions(innerclass_list):
+    """Select unions from innerclass list.
+
+    Args:
+        innerclass_list: raw list with unions and structures
+                         extracted from Dogygen's xml file.
+
+    Returns:
+        Doxygen directives with unions selected from the list.
+
+    """
+
+    rst_output = ""
+    for line in innerclass_list.splitlines():
+        # union is denoted by "union" at the beginning of line
+        if line.find("union") == 0:
+            union_id, union_name = re.split(r"\t+", line)
+            rst_output += ".. doxygenunion:: "
+            rst_output += union_name
+            rst_output += "\n"
+
+    return rst_output
+
+
+def select_structs(innerclass_list):
+    """Select structures from innerclass list.
+
+    Args:
+        innerclass_list: raw list with unions and structures
+                         extracted from Dogygen's xml file.
+
+    Returns:
+        Doxygen directives with structures selected from the list.
+        Note: some structures are excluded as described on code below.
+
+    """
+
+    rst_output = ""
+    for line in innerclass_list.splitlines():
+        # structure is denoted by "struct" at the beginning of line
+        if line.find("struct") == 0:
+            # skip structures that are part of union
+            # they are documented by 'doxygenunion' directive
+            if line.find("::") > 0:
+                continue
+            struct_id, struct_name = re.split(r"\t+", line)
+            rst_output += ".. doxygenstruct:: "
+            rst_output += struct_name
+            rst_output += "\n"
+            rst_output += "    :members:\n"
+            rst_output += "\n"
+
+    return rst_output
+
+
+def get_directives(tree, kind):
+    """Get directives for specific 'kind'.
+
+    Args:
+        tree: the ElementTree 'tree' of XML by Doxygen
+        kind: name of API "kind" to be generated
+
+    Returns:
+        Doxygen directives for selected 'kind'.
+        Note: the header with "kind" name is included.
+
+    """
+
+    rst_output = ""
+    if kind in ["union", "struct"]:
+        innerclass_list = ""
+        for elem in tree.iterfind('compounddef/innerclass'):
+            innerclass_list += elem.attrib["refid"] + "\t" + elem.text + "\n"
+        if kind == "union":
+            rst_output += select_unions(innerclass_list)
+        else:
+            rst_output += select_structs(innerclass_list)
+    else:
+        for elem in tree.iterfind(
+                'compounddef/sectiondef/memberdef[@kind="%s"]' % kind):
+            name = elem.find('name')
+            rst_output += ".. doxygen%s:: " % kind
+            rst_output += name.text + "\n"
+    if rst_output:
+        all_kinds_dict = dict(all_kinds)
+        rst_output = get_rst_header(all_kinds_dict[kind]) + rst_output + "\n"
+
+    return rst_output
+
+
+def generate_directives(header_file_path):
+    """Generate API reference with Doxygen directives for a header file.
+
+    Args:
+        header_file_path: a path to the header file with API.
+
+    Returns:
+        Doxygen directives for the header file.
+
+    """
+
+    api_name = get_api_name(header_file_path)
+
+    # in XLT file name each "_" in the api name is expanded by Doxygen to "__"
+    xlt_api_name = api_name.replace("_", "__")
+    xml_file_path = "%s/%s_8h.xml" % (xml_directory_path, xlt_api_name)
+
+    rst_output = ""
+    rst_output = ".. File automatically generated by 'gen-dxd.py'\n"
+    rst_output += "\n"
+    rst_output += get_rst_header("Header File")
+    rst_output += "* :component_file:`" + header_file_path + "`\n"
+    rst_output += "\n"
+
+    try:
+        import xml.etree.cElementTree as ET
+    except ImportError:
+        import xml.etree.ElementTree as ET
+
+    tree = ET.ElementTree(file=xml_file_path)
+    for i in range(len(all_kinds)):
+        kind = all_kinds[i][0]
+        rst_output += get_directives(tree, kind)
+
+    return rst_output
+
+
+def generate_api_inc_files():
+    """Generate header_file.inc files
+    with API reference made of doxygen directives
+    for each header file
+    specified in the 'INPUT' statement of Doxyfile.
+
+    """
+
+    if not os.path.isdir(xml_directory_path):
+        print "Directory %s does not exist!" % xml_directory_path
+        sys.exit()
+
+    if not os.path.exists(inc_directory_path):
+        os.makedirs(inc_directory_path)
+
+    list_to_generate = get_doxyfile_input()
+    print "Generating 'api_name.inc' files with Doxygen directives"
+    for header_file_path in list_to_generate.splitlines():
+        api_name = get_api_name(header_file_path)
+        inc_file_path = inc_directory_path + "/" + api_name + ".inc"
+        rst_output = generate_directives(header_file_path)
+        inc_file = open(inc_file_path, "w")
+        inc_file.write(rst_output)
+        inc_file.close()
+
+
+if __name__ == "__main__":
+    """The main script that generates
+    Doxygen directives.
+
+    """
+
+    # Process command line arguments, if any
+    if len(sys.argv) > 1:
+        if not os.path.isdir(xml_directory_path):
+            print "Directory %s does not exist!" % xml_directory_path
+            sys.exit()
+        header_file_path = sys.argv[1]
+        api_name = get_api_name(header_file_path)
+        if api_name:
+            rst_output = generate_directives(header_file_path)
+            print "Doxygen directives for '%s'" % header_file_path
+            print
+            print rst_output
+        else:
+            print "Options to execute 'gen-dxd.py' application:"
+            print "1: $ python gen-dxd.py"
+            print "   Generate API 'header_file.inc' files for headers defined in '%s'" % doxyfile_path
+            print "2: $ python gen-dxd.py header_file_path"
+            print "   Print out Doxygen directives for a single header file"
+            print "   example: $ python gen-dxd.py mdns/include/mdns.h"
+            print "   NOTE: Run Doxygen first to get XML files for the header file"
+
+        sys.exit()
+
+    # No command line arguments given
+    generate_api_inc_files()

docs/hw-reference/index.rst

@@ -7,6 +7,7 @@ Hardware Reference
    Technical Reference Manual (PDF) <http://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>
    Pin List and Functions (PDF) <http://espressif.com/sites/default/files/documentation/esp32_chip_pin_list_en.pdf>
    Chip Pinout (PDF) <http://espressif.com/sites/default/files/documentation/esp32_pinout_v1_0.pdf>
+   ESP32 Hardware Design Guidelines (PDF) <http://espressif.com/sites/default/files/documentation/esp32_hardware_design_guidelines_en.pdf>
    Silicon Errata (PDF) <http://espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf>
    Modules and Boards <modules-and-boards>
-   
+