docs: add new top-level docs builder that builds docs for a single chip

docs/Doxyfile

@@ -24,270 +24,270 @@ INPUT = \
     ##
     ## Wi-Fi - API Reference
     ##
-    ../../components/esp_wifi/include/esp_wifi.h \
+    $(IDF_PATH)/components/esp_wifi/include/esp_wifi.h \
-    ../../components/esp_wifi/include/esp_wifi_types.h \
+    $(IDF_PATH)/components/esp_wifi/include/esp_wifi_types.h \
-    ../../components/esp_wifi/include/esp_smartconfig.h \
+    $(IDF_PATH)/components/esp_wifi/include/esp_smartconfig.h \
-    ../../components/esp_wifi/include/esp_now.h \
+    $(IDF_PATH)/components/esp_wifi/include/esp_now.h \
-    ../../components/esp_wifi/include/esp_wifi_default.h \
+    $(IDF_PATH)/components/esp_wifi/include/esp_wifi_default.h \
     ## Mesh - API Reference
-    ../../components/esp_wifi/include/esp_mesh.h \
+    $(IDF_PATH)/components/esp_wifi/include/esp_mesh.h \
     ## Event loop - API Reference
-    ../../components/esp_event/include/esp_event.h \
+    $(IDF_PATH)/components/esp_event/include/esp_event.h \
-    ../../components/esp_event/include/esp_event_base.h \
+    $(IDF_PATH)/components/esp_event/include/esp_event_base.h \
-    ../../components/esp_event/include/esp_event_legacy.h \
+    $(IDF_PATH)/components/esp_event/include/esp_event_legacy.h \
     ## Bluetooth - API Reference
     ## Controller && VHCI
-    ../../components/bt/include/esp_bt.h \
+    $(IDF_PATH)/components/bt/include/esp_bt.h \
     ## Bluetooth COMMON
     ## Issue with __attribute__
-    ../../components/bt/host/bluedroid/api/include/api/esp_bt_defs.h \
+    $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_bt_defs.h \
-    ../../components/bt/host/bluedroid/api/include/api/esp_bt_main.h \
+    $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_bt_main.h \
-    ../../components/bt/host/bluedroid/api/include/api/esp_bt_device.h \
+    $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_bt_device.h \
     ## Bluetooth LE
-    ../../components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h \
+    $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h \
     ## Issue with __attribute__
-    ../../components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h \
+    $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h \
-    ../../components/bt/host/bluedroid/api/include/api/esp_gatts_api.h \
+    $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_gatts_api.h \
-    ../../components/bt/host/bluedroid/api/include/api/esp_gattc_api.h \
+    $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h \
-    ../../components/bt/host/bluedroid/api/include/api/esp_blufi_api.h \
+    $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_blufi_api.h \
     ## Bluetooth Classic
-    ../../components/bt/host/bluedroid/api/include/api/esp_gap_bt_api.h \
+    $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_gap_bt_api.h \
     ## Issue with __attribute__
-    ../../components/bt/host/bluedroid/api/include/api/esp_a2dp_api.h \
+    $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_a2dp_api.h \
-    ../../components/bt/host/bluedroid/api/include/api/esp_avrc_api.h \
+    $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_avrc_api.h \
-    ../../components/bt/host/bluedroid/api/include/api/esp_spp_api.h \
+    $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_spp_api.h \
-    ../../components/bt/host/bluedroid/api/include/api/esp_hf_defs.h \
+    $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_hf_defs.h \
-    ../../components/bt/host/bluedroid/api/include/api/esp_hf_client_api.h \
+    $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_hf_client_api.h \
-    ../../components/bt/host/bluedroid/api/include/api/esp_hf_ag_api.h \
+    $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_hf_ag_api.h \
     ## NimBLE related Bluetooth APIs
-    ../../components/bt/host/nimble/esp-hci/include/esp_nimble_hci.h \
+    $(IDF_PATH)/components/bt/host/nimble/esp-hci/include/esp_nimble_hci.h \
     ## ESP BLE Mesh APIs
-    ../../components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_common_api.h \
+    $(IDF_PATH)/components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_common_api.h \
-    ../../components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_local_data_operation_api.h \
+    $(IDF_PATH)/components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_local_data_operation_api.h \
-    ../../components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_low_power_api.h \
+    $(IDF_PATH)/components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_low_power_api.h \
-    ../../components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_networking_api.h \
+    $(IDF_PATH)/components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_networking_api.h \
-    ../../components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_provisioning_api.h \
+    $(IDF_PATH)/components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_provisioning_api.h \
-    ../../components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_proxy_api.h \
+    $(IDF_PATH)/components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_proxy_api.h \
-    ../../components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_config_model_api.h \
+    $(IDF_PATH)/components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_config_model_api.h \
-    ../../components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_generic_model_api.h \
+    $(IDF_PATH)/components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_generic_model_api.h \
-    ../../components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_health_model_api.h \
+    $(IDF_PATH)/components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_health_model_api.h \
-    ../../components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_lighting_model_api.h \
+    $(IDF_PATH)/components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_lighting_model_api.h \
-    ../../components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_sensor_model_api.h \
+    $(IDF_PATH)/components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_sensor_model_api.h \
-    ../../components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_time_scene_model_api.h \
+    $(IDF_PATH)/components/bt/esp_ble_mesh/api/models/include/esp_ble_mesh_time_scene_model_api.h \
-    ../../components/bt/esp_ble_mesh/api/esp_ble_mesh_defs.h \
+    $(IDF_PATH)/components/bt/esp_ble_mesh/api/esp_ble_mesh_defs.h \
     ##
     ## Ethernet - API Reference
     ##
-    ../../components/esp_eth/include/esp_eth.h \
+    $(IDF_PATH)/components/esp_eth/include/esp_eth.h \
-    ../../components/esp_eth/include/esp_eth_com.h \
+    $(IDF_PATH)/components/esp_eth/include/esp_eth_com.h \
-    ../../components/esp_eth/include/esp_eth_mac.h \
+    $(IDF_PATH)/components/esp_eth/include/esp_eth_mac.h \
-    ../../components/esp_eth/include/esp_eth_phy.h \
+    $(IDF_PATH)/components/esp_eth/include/esp_eth_phy.h \
-    ../../components/esp_eth/include/esp_eth_netif_glue.h \
+    $(IDF_PATH)/components/esp_eth/include/esp_eth_netif_glue.h \
     ##
     ## Peripherals - API Reference
     ##
-    ../../components/driver/include/driver/adc.h \
+    $(IDF_PATH)/components/driver/include/driver/adc.h \
-    ../../components/driver/include/driver/can.h \
+    $(IDF_PATH)/components/driver/include/driver/can.h \
-    ../../components/soc/include/hal/can_types.h \
+    $(IDF_PATH)/components/soc/include/hal/can_types.h \
-    ../../components/driver/include/driver/dac.h \
+    $(IDF_PATH)/components/driver/include/driver/dac.h \
-    ../../components/driver/include/driver/gpio.h \
+    $(IDF_PATH)/components/driver/include/driver/gpio.h \
-    ../../components/driver/include/driver/rtc_io.h \
+    $(IDF_PATH)/components/driver/include/driver/rtc_io.h \
-    ../../components/driver/include/driver/i2c.h \
+    $(IDF_PATH)/components/driver/include/driver/i2c.h \
-    ../../components/driver/include/driver/i2s.h \
+    $(IDF_PATH)/components/driver/include/driver/i2s.h \
-    ../../components/driver/include/driver/ledc.h \
+    $(IDF_PATH)/components/driver/include/driver/ledc.h \
-    ../../components/driver/include/driver/mcpwm.h \
+    $(IDF_PATH)/components/driver/include/driver/mcpwm.h \
-    ../../components/soc/include/hal/mcpwm_types.h \
+    $(IDF_PATH)/components/soc/include/hal/mcpwm_types.h \
-    ../../components/driver/include/driver/pcnt.h \
+    $(IDF_PATH)/components/driver/include/driver/pcnt.h \
-    ../../components/driver/include/driver/rmt.h \
+    $(IDF_PATH)/components/driver/include/driver/rmt.h \
-    ../../components/driver/include/driver/sigmadelta.h \
+    $(IDF_PATH)/components/driver/include/driver/sigmadelta.h \
-    ../../components/driver/include/driver/spi_common.h \
+    $(IDF_PATH)/components/driver/include/driver/spi_common.h \
-    ../../components/driver/include/driver/spi_master.h \
+    $(IDF_PATH)/components/driver/include/driver/spi_master.h \
-    ../../components/driver/include/driver/spi_slave.h \
+    $(IDF_PATH)/components/driver/include/driver/spi_slave.h \
-    ../../components/driver/esp32s2/include/temp_sensor.h \
+    $(IDF_PATH)/components/driver/esp32s2/include/temp_sensor.h \
-    ../../components/driver/include/driver/timer.h \
+    $(IDF_PATH)/components/driver/include/driver/timer.h \
-    ../../components/driver/include/driver/touch_pad.h \
+    $(IDF_PATH)/components/driver/include/driver/touch_pad.h \
-    ../../components/driver/include/driver/uart.h \
+    $(IDF_PATH)/components/driver/include/driver/uart.h \
-    ../../components/esp_adc_cal/include/esp_adc_cal.h \
+    $(IDF_PATH)/components/esp_adc_cal/include/esp_adc_cal.h \
-    ../../components/soc/include/hal/rmt_types.h \
+    $(IDF_PATH)/components/soc/include/hal/rmt_types.h \
-    ../../components/soc/include/hal/spi_types.h \
+    $(IDF_PATH)/components/soc/include/hal/spi_types.h \
-    ../../components/soc/include/hal/pcnt_types.h \
+    $(IDF_PATH)/components/soc/include/hal/pcnt_types.h \
-    ../../components/soc/include/hal/i2s_types.h \
+    $(IDF_PATH)/components/soc/include/hal/i2s_types.h \
-    ../../components/soc/include/hal/rtc_io_types.h \
+    $(IDF_PATH)/components/soc/include/hal/rtc_io_types.h \
-    ../../components/soc/include/hal/sigmadelta_types.h \
+    $(IDF_PATH)/components/soc/include/hal/sigmadelta_types.h \
-    ../../components/soc/include/hal/timer_types.h \
+    $(IDF_PATH)/components/soc/include/hal/timer_types.h \
-    ../../components/soc/include/hal/ledc_types.h \
+    $(IDF_PATH)/components/soc/include/hal/ledc_types.h \
-    ../../components/soc/include/hal/i2c_types.h \
+    $(IDF_PATH)/components/soc/include/hal/i2c_types.h \
-    ../../components/soc/include/hal/dac_types.h \
+    $(IDF_PATH)/components/soc/include/hal/dac_types.h \
-    ../../components/soc/include/hal/adc_types.h \
+    $(IDF_PATH)/components/soc/include/hal/adc_types.h \
-    ../../components/soc/include/hal/gpio_types.h \
+    $(IDF_PATH)/components/soc/include/hal/gpio_types.h \
-    ../../components/soc/include/hal/uart_types.h \
+    $(IDF_PATH)/components/soc/include/hal/uart_types.h \
-    ../../components/soc/include/hal/touch_sensor_types.h \
+    $(IDF_PATH)/components/soc/include/hal/touch_sensor_types.h \
-    ../../components/soc/esp32/include/soc/adc_channel.h \
+    $(IDF_PATH)/components/soc/esp32/include/soc/adc_channel.h \
-    ../../components/soc/esp32/include/soc/dac_channel.h \
+    $(IDF_PATH)/components/soc/esp32/include/soc/dac_channel.h \
-    ../../components/soc/esp32/include/soc/touch_sensor_channel.h \
+    $(IDF_PATH)/components/soc/esp32/include/soc/touch_sensor_channel.h \
-    ../../components/soc/esp32/include/soc/uart_channel.h \
+    $(IDF_PATH)/components/soc/esp32/include/soc/uart_channel.h \
-    ../../components/soc/esp32/include/soc/rtc_io_channel.h \
+    $(IDF_PATH)/components/soc/esp32/include/soc/rtc_io_channel.h \
     ## esp_netif - API Reference
-    ../../components/esp_netif/include/esp_netif.h \
+    $(IDF_PATH)/components/esp_netif/include/esp_netif.h \
-    ../../components/esp_netif/include/esp_netif_net_stack.h \
+    $(IDF_PATH)/components/esp_netif/include/esp_netif_net_stack.h \
     ##
     ## Protocols - API Reference
     ##
     ## ESP-TLS
-    ../../components/esp-tls/esp_tls.h \
+    $(IDF_PATH)/components/esp-tls/esp_tls.h \
     ## MQTT
-    ../../components/mqtt/esp-mqtt/include/mqtt_client.h \
+    $(IDF_PATH)/components/mqtt/esp-mqtt/include/mqtt_client.h \
     ## ICMP-ECHO
-    ../../components/lwip/include/apps/ping/ping_sock.h \
+    $(IDF_PATH)/components/lwip/include/apps/ping/ping_sock.h \
     ## SNTP
-    ../../components/lwip/include/apps/sntp/sntp.h \
+    $(IDF_PATH)/components/lwip/include/apps/sntp/sntp.h \
     ## mDNS
-    ../../components/mdns/include/mdns.h \
+    $(IDF_PATH)/components/mdns/include/mdns.h \
-    ../../components/esp_http_client/include/esp_http_client.h \
+    $(IDF_PATH)/components/esp_http_client/include/esp_http_client.h \
-    ../../components/esp_websocket_client/include/esp_websocket_client.h \
+    $(IDF_PATH)/components/esp_websocket_client/include/esp_websocket_client.h \
     ## HTTP / HTTPS Server
-    ../../components/esp_http_server/include/esp_http_server.h \
+    $(IDF_PATH)/components/esp_http_server/include/esp_http_server.h \
-    ../../components/esp_https_server/include/esp_https_server.h \
+    $(IDF_PATH)/components/esp_https_server/include/esp_https_server.h \
     ## ESP Local Ctrl
-    ../../components/esp_local_ctrl/include/esp_local_ctrl.h \
+    $(IDF_PATH)/components/esp_local_ctrl/include/esp_local_ctrl.h \
     ## ESP Serial Slave Link
-    ../../components/esp_serial_slave_link/include/esp_serial_slave_link/essl.h \
+    $(IDF_PATH)/components/esp_serial_slave_link/include/esp_serial_slave_link/essl.h \
-    ../../components/esp_serial_slave_link/include/esp_serial_slave_link/essl_sdio.h \
+    $(IDF_PATH)/components/esp_serial_slave_link/include/esp_serial_slave_link/essl_sdio.h \
     ##
     ## Provisioning - API Reference
     ##
     ## Protocol Communication
-    ../../components/protocomm/include/common/protocomm.h \
+    $(IDF_PATH)/components/protocomm/include/common/protocomm.h \
-    ../../components/protocomm/include/security/protocomm_security.h \
+    $(IDF_PATH)/components/protocomm/include/security/protocomm_security.h \
-    ../../components/protocomm/include/security/protocomm_security0.h \
+    $(IDF_PATH)/components/protocomm/include/security/protocomm_security0.h \
-    ../../components/protocomm/include/security/protocomm_security1.h \
+    $(IDF_PATH)/components/protocomm/include/security/protocomm_security1.h \
-    ../../components/protocomm/include/transports/protocomm_ble.h \
+    $(IDF_PATH)/components/protocomm/include/transports/protocomm_ble.h \
-    ../../components/protocomm/include/transports/protocomm_console.h \
+    $(IDF_PATH)/components/protocomm/include/transports/protocomm_console.h \
-    ../../components/protocomm/include/transports/protocomm_httpd.h \
+    $(IDF_PATH)/components/protocomm/include/transports/protocomm_httpd.h \
     ## WiFi Provisioning
-    ../../components/wifi_provisioning/include/wifi_provisioning/manager.h \
+    $(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/manager.h \
-    ../../components/wifi_provisioning/include/wifi_provisioning/scheme_ble.h \
+    $(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/scheme_ble.h \
-    ../../components/wifi_provisioning/include/wifi_provisioning/scheme_softap.h \
+    $(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/scheme_softap.h \
-    ../../components/wifi_provisioning/include/wifi_provisioning/scheme_console.h \
+    $(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/scheme_console.h \
-    ../../components/wifi_provisioning/include/wifi_provisioning/wifi_config.h \
+    $(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/wifi_config.h \
-    ../../components/wifi_provisioning/include/wifi_provisioning/wifi_scan.h \
+    $(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/wifi_scan.h \
     ##
     ## Storage - API Reference
     ##
     ## SPI Flash and Partition APIs
-    ../../components/spi_flash/include/esp_flash_spi_init.h \
+    $(IDF_PATH)/components/spi_flash/include/esp_flash_spi_init.h \
-    ../../components/spi_flash/include/esp_flash.h \
+    $(IDF_PATH)/components/spi_flash/include/esp_flash.h \
-    ../../components/spi_flash/include/esp_partition.h \
+    $(IDF_PATH)/components/spi_flash/include/esp_partition.h \
-    ../../components/bootloader_support/include/esp_flash_encrypt.h \
+    $(IDF_PATH)/components/bootloader_support/include/esp_flash_encrypt.h \
-    ../../components/soc/include/hal/spi_flash_types.h \
+    $(IDF_PATH)/components/soc/include/hal/spi_flash_types.h \
     ## SPIFFS
-    ../../components/spiffs/include/esp_spiffs.h \
+    $(IDF_PATH)/components/spiffs/include/esp_spiffs.h \
     ## SD/MMC Card Host
-    ../../components/sdmmc/include/sdmmc_cmd.h \
+    $(IDF_PATH)/components/sdmmc/include/sdmmc_cmd.h \
-    ../../components/driver/include/driver/sdmmc_host.h \
+    $(IDF_PATH)/components/driver/include/driver/sdmmc_host.h \
-    ../../components/driver/include/driver/sdmmc_types.h \
+    $(IDF_PATH)/components/driver/include/driver/sdmmc_types.h \
-    ../../components/driver/include/driver/sdspi_host.h \
+    $(IDF_PATH)/components/driver/include/driver/sdspi_host.h \
     ## SDIO slave
-    ../../components/driver/include/driver/sdio_slave.h \
+    $(IDF_PATH)/components/driver/include/driver/sdio_slave.h \
-    ../../components/soc/include/hal/sdio_slave_types.h \
+    $(IDF_PATH)/components/soc/include/hal/sdio_slave_types.h \
     ## Non-Volatile Storage
-    ../../components/nvs_flash/include/nvs.h \
+    $(IDF_PATH)/components/nvs_flash/include/nvs.h \
-    ../../components/nvs_flash/include/nvs_flash.h \
+    $(IDF_PATH)/components/nvs_flash/include/nvs_flash.h \
     ## Virtual Filesystem
-    ../../components/vfs/include/esp_vfs.h \
+    $(IDF_PATH)/components/vfs/include/esp_vfs.h \
-    ../../components/vfs/include/esp_vfs_dev.h \
+    $(IDF_PATH)/components/vfs/include/esp_vfs_dev.h \
-    ../../components/vfs/include/esp_vfs_semihost.h \
+    $(IDF_PATH)/components/vfs/include/esp_vfs_semihost.h \
     ## FAT Filesystem
     ## NOTE: for two lines below header_file.inc is not used
-    ../../components/fatfs/vfs/esp_vfs_fat.h \
+    $(IDF_PATH)/components/fatfs/vfs/esp_vfs_fat.h \
-    ../../components/fatfs/diskio/diskio_impl.h \
+    $(IDF_PATH)/components/fatfs/diskio/diskio_impl.h \
-    ../../components/fatfs/diskio/diskio_sdmmc.h \
+    $(IDF_PATH)/components/fatfs/diskio/diskio_sdmmc.h \
-    ../../components/fatfs/diskio/diskio_wl.h \
+    $(IDF_PATH)/components/fatfs/diskio/diskio_wl.h \
-    ../../components/fatfs/diskio/diskio_rawflash.h \
+    $(IDF_PATH)/components/fatfs/diskio/diskio_rawflash.h \
     ## Wear Levelling
-    ../../components/wear_levelling/include/wear_levelling.h \
+    $(IDF_PATH)/components/wear_levelling/include/wear_levelling.h \
     ##
     ## System - API Reference
     ##
     ## Memory Allocation    #
-    ../../components/heap/include/esp_heap_caps.h \
+    $(IDF_PATH)/components/heap/include/esp_heap_caps.h \
-    ../../components/heap/include/esp_heap_trace.h \
+    $(IDF_PATH)/components/heap/include/esp_heap_trace.h \
-    ../../components/heap/include/esp_heap_caps_init.h \
+    $(IDF_PATH)/components/heap/include/esp_heap_caps_init.h \
-    ../../components/heap/include/multi_heap.h \
+    $(IDF_PATH)/components/heap/include/multi_heap.h \
     ## Himem
-    ../../components/esp32/include/esp32/himem.h \
+    $(IDF_PATH)/components/esp32/include/esp32/himem.h \
     ## Interrupt Allocation
-    ../../components/esp32/include/esp_intr_alloc.h \
+    $(IDF_PATH)/components/esp32/include/esp_intr_alloc.h \
     ## Watchdogs
     ## NOTE: for two lines below header_file.inc is not used
-    ../../components/esp_common/include/esp_int_wdt.h \
+    $(IDF_PATH)/components/esp_common/include/esp_int_wdt.h \
-    ../../components/esp_common/include/esp_task_wdt.h \
+    $(IDF_PATH)/components/esp_common/include/esp_task_wdt.h \
     ## Hooks
-    ../../components/esp_common/include/esp_freertos_hooks.h \
+    $(IDF_PATH)/components/esp_common/include/esp_freertos_hooks.h \
     ## Inter-Processor Call
-    ../../components/esp_common/include/esp_ipc.h \
+    $(IDF_PATH)/components/esp_common/include/esp_ipc.h \
     ## Call Function with External stack
-    ../../components/esp_common/include/esp_expression_with_stack.h \
+    $(IDF_PATH)/components/esp_common/include/esp_expression_with_stack.h \
     ## Over The Air Updates (OTA)
-    ../../components/app_update/include/esp_ota_ops.h \
+    $(IDF_PATH)/components/app_update/include/esp_ota_ops.h \
     ## ESP HTTPS OTA
-    ../../components/esp_https_ota/include/esp_https_ota.h \
+    $(IDF_PATH)/components/esp_https_ota/include/esp_https_ota.h \
     ## Sleep
-    ../../components/esp32/include/esp_sleep.h \
+    $(IDF_PATH)/components/esp32/include/esp_sleep.h \
     ## Logging
-    ../../components/log/include/esp_log.h \
+    $(IDF_PATH)/components/log/include/esp_log.h \
     ## Base MAC address
     ## NOTE: for line below header_file.inc is not used
-    ../../components/esp_common/include/esp_system.h \
+    $(IDF_PATH)/components/esp_common/include/esp_system.h \
     ## IDF version
-    ../../components/esp_common/include/esp_idf_version.h \
+    $(IDF_PATH)/components/esp_common/include/esp_idf_version.h \
     ##
     ## ULP Coprocessor - API Guides
     ##
     ## NOTE: for line below header_file.inc is not used
-    ../../components/ulp/include/esp32/ulp.h \
+    $(IDF_PATH)/components/ulp/include/esp32/ulp.h \
-    ../../components/ulp/include/ulp_common.h \
+    $(IDF_PATH)/components/ulp/include/ulp_common.h \
     ##
     ## Application Level Tracing - API Reference
     ##
-    ../../components/app_trace/include/esp_app_trace.h \
+    $(IDF_PATH)/components/app_trace/include/esp_app_trace.h \
-    ../../components/app_trace/include/esp_sysview_trace.h \
+    $(IDF_PATH)/components/app_trace/include/esp_sysview_trace.h \
     ### Power management
-    ../../components/esp_common/include/esp_pm.h \
+    $(IDF_PATH)/components/esp_common/include/esp_pm.h \
-    ../../components/esp32/include/esp32/pm.h \
+    $(IDF_PATH)/components/esp32/include/esp32/pm.h \
     ### esp_timer, High Resolution Timer
-    ../../components/esp_timer/include/esp_timer.h \
+    $(IDF_PATH)/components/esp_timer/include/esp_timer.h \
     ### esp_event, Event Loop Library
-    ../../components/esp_event/include/esp_event.h \
+    $(IDF_PATH)/components/esp_event/include/esp_event.h \
-    ../../components/esp_event/include/esp_event_base.h \
+    $(IDF_PATH)/components/esp_event/include/esp_event_base.h \
     ### eFuse Manager
-    ../../components/efuse/include/esp_efuse.h \
+    $(IDF_PATH)/components/efuse/include/esp_efuse.h \
     ### App Image Format
-    ../../components/bootloader_support/include/esp_app_format.h \
+    $(IDF_PATH)/components/bootloader_support/include/esp_app_format.h \
     ### ESP Pthread parameters
-    ../../components/pthread/include/esp_pthread.h \
+    $(IDF_PATH)/components/pthread/include/esp_pthread.h \
     ###
     ### FreeRTOS
     ###
-    ../../components/freertos/include/freertos/task.h \
+    $(IDF_PATH)/components/freertos/include/freertos/task.h \
-    ../../components/freertos/include/freertos/queue.h \
+    $(IDF_PATH)/components/freertos/include/freertos/queue.h \
-    ../../components/freertos/include/freertos/semphr.h \
+    $(IDF_PATH)/components/freertos/include/freertos/semphr.h \
-    ../../components/freertos/include/freertos/timers.h \
+    $(IDF_PATH)/components/freertos/include/freertos/timers.h \
-    ../../components/freertos/include/freertos/event_groups.h \
+    $(IDF_PATH)/components/freertos/include/freertos/event_groups.h \
     ### Ringbuffer
-    ../../components/esp_ringbuf/include/freertos/ringbuf.h \
+    $(IDF_PATH)/components/esp_ringbuf/include/freertos/ringbuf.h \
     ### Helper functions for error codes
-    ../../components/esp_common/include/esp_err.h \
+    $(IDF_PATH)/components/esp_common/include/esp_err.h \
     ### System APIs
-    ../../components/esp_common/include/esp_system.h \
+    $(IDF_PATH)/components/esp_common/include/esp_system.h \
     ### Modbus controller component header file
-    ../../components/freemodbus/common/include/esp_modbus_common.h \
+    $(IDF_PATH)/components/freemodbus/common/include/esp_modbus_common.h \
-    ../../components/freemodbus/common/include/esp_modbus_slave.h \
+    $(IDF_PATH)/components/freemodbus/common/include/esp_modbus_slave.h \
-    ../../components/freemodbus/common/include/esp_modbus_master.h \
+    $(IDF_PATH)/components/freemodbus/common/include/esp_modbus_master.h \
      ### Performance Monitor component header file
-     ../../components/perfmon/include/xtensa_perfmon_access.h \
+     $(IDF_PATH)/components/perfmon/include/xtensa_perfmon_access.h \
-     ../../components/perfmon/include/xtensa_perfmon_apis.h \
+     $(IDF_PATH)/components/perfmon/include/xtensa_perfmon_apis.h \
-     ../../components/perfmon/include/xtensa_perfmon_masks.h
+     $(IDF_PATH)/components/perfmon/include/xtensa_perfmon_masks.h
 
 
 ## Get warnings for functions that have no documentation for their parameters or return value

docs/build_docs.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python
+#
+# Top-level docs builder
+#
+# This is just a front-end to sphinx-build that can call it multiple times for different language/target combinations
+#
+# Will build out to _build/LANG/TARGET by default
+#
+# Specific custom docs functionality should be added in conf_common.py or in a Sphinx extension, not here.
+#
+import argparse
+import os
+import os.path
+import subprocess
+import sys
+
+LANGUAGES = ["en", "zh_CN"]
+TARGETS = ["esp32", "esp32s2"]
+
+def main():
+    # check Python dependencies for docs
+    try:
+        subprocess.check_call([sys.executable,
+                               os.path.join(os.environ["IDF_PATH"],
+                                            "tools",
+                                            "check_python_dependencies.py"),
+                               "-r",
+                               "{}/docs/requirements.txt".format(os.environ["IDF_PATH"])
+                               ])
+    except subprocess.CalledProcessError:
+        raise SystemExit(2)  # stdout will already have these errors
+
+    parser = argparse.ArgumentParser(description='build_docs.py: Build IDF docs',
+                                     prog='build_docs.py')
+    parser.add_argument("--language", "-l", choices=LANGUAGES,
+                        required=False)
+    parser.add_argument("--target", "-t", choices=TARGETS, required=False)
+    parser.add_argument("--build-dir", "-b", type=str, default="_build")
+
+    args = parser.parse_args()
+
+    if args.language is None:
+        print("Building all languages")
+        languages = LANGUAGES
+    else:
+        languages = [ args.language ]
+
+    if args.target is None:
+        print("Building all targets")
+        targets = TARGETS
+    else:
+        targets = [ args.target ]
+
+    for language in languages:
+        for target in targets:
+            build_dir = os.path.realpath(os.path.join(args.build_dir, language, target))
+            build_docs(language, target, build_dir)
+
+
+def build_docs(language, target, build_dir):
+    print("Building language:%s target:%s build_dir:%s" % (language, target, build_dir))
+    try:
+        os.makedirs(build_dir)
+    except OSError:
+        pass
+    try:
+        environ = {}
+        environ.update(os.environ)
+        environ['BUILDDIR'] = build_dir
+
+        args = [sys.executable, "-m", "sphinx",
+                "-b", "html",  # TODO: PDFs
+                "-d", os.path.join(build_dir, "doctrees"),
+                # TODO: support multiple sphinx-warning.log files, somehow
+                "-w", "sphinx-warning.log",
+                "-D", "idf_target={}".format(target),
+                os.path.join(os.path.abspath(os.path.dirname(__file__)), language), # srcdir for this language
+                os.path.join(build_dir, "html")                    # build directory
+        ]
+        cwd = build_dir  # also run sphinx in the build directory
+        print("Running '{}'".format(" ".join(args)))
+        subprocess.check_call(args, cwd=cwd, env=environ)
+    except subprocess.CalledProcessError:
+        print("Sphinx failed for language:%s target:%s" % (language, target))
+        raise SystemExit(1)  # rest of the details should be in stdout
+
+
+if __name__ == "__main__":
+    main()

docs/conf_common.py

@@ -31,11 +31,11 @@ from local_util import run_cmd_get_output, copy_if_modified, call_with_python
 sys.setrecursionlimit(3500)
 
 try:
-    builddir = os.environ['BUILDDIR']
+    build_dir = os.environ['BUILDDIR']
 except KeyError:
-    builddir = '_build'
+    build_dir = '_build'
 
-builddir = os.path.abspath(builddir)
+build_dir = os.path.abspath(build_dir)
 
 # Fill in a default IDF_PATH if it's missing (ie when Read The Docs is building the docs)
 try:
@@ -43,11 +43,15 @@ try:
 except KeyError:
     idf_path = os.path.realpath(os.path.join(os.path.dirname(__file__), '..'))
 
-# Set the idf_target chip. This is a hack right now.
+docs_root = os.path.join(idf_path, "docs")
-idf_target = 'esp32s2'
 
 try:
-    os.mkdir(builddir)
+    os.mkdir(build_dir)
+except OSError:
+    pass
+
+try:
+    os.mkdir(os.path.join(build_dir, 'inc'))
 except OSError:
     pass
 
@@ -56,16 +60,16 @@ except OSError:
 # (Note: this is in a function as it needs to access configuration to get the language)
 def generate_version_specific_includes(app):
     print("Generating version-specific includes...")
-    version_tmpdir = '{}/version_inc'.format(builddir)
+    version_tmpdir = '{}/version_inc'.format(build_dir)
-    call_with_python('../gen-version-specific-includes.py {} {}'.format(app.config.language, version_tmpdir))
+    call_with_python('{}/gen-version-specific-includes.py {} {}'.format(docs_root, app.config.language, version_tmpdir))
-    copy_if_modified(version_tmpdir, '{}/inc'.format(builddir))
+    copy_if_modified(version_tmpdir, '{}/inc'.format(build_dir))
 
 # Generate toolchain download links
 print("Generating toolchain download links")
 base_url = 'https://dl.espressif.com/dl/'
-toolchain_tmpdir = '{}/toolchain_inc'.format(builddir)
+toolchain_tmpdir = '{}/toolchain_inc'.format(build_dir)
-call_with_python('../gen-toolchain-links.py ../../tools/toolchain_versions.mk {} {}'.format(base_url, toolchain_tmpdir))
+call_with_python('{}/gen-toolchain-links.py ../../tools/toolchain_versions.mk {} {}'.format(docs_root, base_url, toolchain_tmpdir))
-copy_if_modified(toolchain_tmpdir, '{}/inc'.format(builddir))
+copy_if_modified(toolchain_tmpdir, '{}/inc'.format(build_dir))
 
 print("Generating IDF Tools list")
 os.environ["IDF_MAINTAINER"] = "1"
@@ -100,6 +104,7 @@ extensions = ['breathe',
               'kconfig_reference',
               'doxygen_idf',
               'sphinx.ext.todo',
+              'include_build_file',
               ]
 
 # sphinx.ext.todo extension parameters
@@ -115,7 +120,7 @@ seqdiag_antialias = True
 # Doxygen regenerates files in 'xml/' directory every time,
 # but we copy files to 'xml_in/' only when they change, to speed up
 # incremental builds.
-breathe_projects = {"esp32-idf": "xml_in/"}
+breathe_projects = {"esp32-idf": os.path.join(build_dir, "xml_in/")}
 breathe_default_project = "esp32-idf"
 
 # Add any paths that contain templates here, relative to this directory.
@@ -364,5 +369,6 @@ texinfo_documents = [
 # Override RTD CSS theme to introduce the theme corrections
 # https://github.com/rtfd/sphinx_rtd_theme/pull/432
 def setup(app):
+    app.config.build_dir = build_dir
     app.add_stylesheet('theme_overrides.css')
     generate_version_specific_includes(app)

docs/docs_common.mk

@@ -1,217 +0,0 @@
-# "Common" Makefile for Sphinx documentation
-#
-# (included from en/Makefile & zh_CN/Makefile
-#
-# NOTE: This makefile runs with cwd=either en or zh_CN subfolder, so this
-# (docs/) directory is '..' relative to it.
-
-# ************ IMPORTANT *****************
-#
-# ReadTheDocs DOES NOT USE THIS MAKEFILE,
-# so any behaviour additions must be
-# done via Sphinx Config not here
-#
-# ****************************************
-
-# You can set these variables from the command line.
-SPHINXOPTS    =
-# note: this is changed from sphinx-build so it depends on default python interpreter, not on /bin/sphinx-build
-# (which will be the most recently installed version of sphinx and may not match)
-SPHINXBUILD   = python -m sphinx
-PAPER         =
-BUILDDIR      = _build
-
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-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) .
-
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext dependencies version-specific-includes check_python_packages
-
-help:
-	@echo "Please use \`make <target>\' where <target> is one of"
-	@echo "  html       to make standalone HTML files"
-	@echo "  dirhtml    to make HTML files named index.html in directories"
-	@echo "  singlehtml to make a single large HTML file"
-	@echo "  pickle     to make pickle files"
-	@echo "  json       to make JSON files"
-	@echo "  htmlhelp   to make HTML files and a HTML help project"
-	@echo "  qthelp     to make HTML files and a qthelp project"
-	@echo "  devhelp    to make HTML files and a Devhelp project"
-	@echo "  epub       to make an epub"
-	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
-	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
-	@echo "  text       to make text files"
-	@echo "  man        to make manual pages"
-	@echo "  texinfo    to make Texinfo files"
-	@echo "  info       to make Texinfo files and run them through makeinfo"
-	@echo "  gettext    to make PO message catalogs"
-	@echo "  changes    to make an overview of all changed/added/deprecated items"
-	@echo "  xml        to make Docutils-native XML files"
-	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
-	@echo "  linkcheck  to check all external links for integrity"
-	@echo "  doctest    to run all doctests embedded in the documentation (if enabled) "
-
-clean:
-	rm -rf $(BUILDDIR)/*
-
-# Notify users when some of the required python packages are not installed.
-# Note: This is intended to help developers who generate the documentation on their local machine. Read The Docs uses
-# the requirements.txt file directly and calls sphinx also directly without the use of the makefile!
-check_python_packages:
-	$(IDF_PATH)/tools/check_python_dependencies.py -r $(IDF_PATH)/docs/requirements.txt
-
-html: | check_python_packages
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-dirhtml: | check_python_packages
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
-
-singlehtml: | check_python_packages
-	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
-	@echo
-	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
-
-pickle: | check_python_packages
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-json: | check_python_packages
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
-	@echo
-	@echo "Build finished; now you can process the JSON files."
-
-htmlhelp: | check_python_packages
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in $(BUILDDIR)/htmlhelp."
-
-qthelp: | check_python_packages
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
-	@echo
-	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
-	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/ReadtheDocsTemplate.qhcp"
-	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/ReadtheDocsTemplate.qhc"
-
-devhelp: | check_python_packages
-	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
-	@echo
-	@echo "Build finished."
-	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/ReadtheDocsTemplate"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/ReadtheDocsTemplate"
-	@echo "# devhelp"
-
-epub: | check_python_packages
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
-	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
-
-latex: | check_python_packages
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
-	@echo "Run \`make' in that directory to run these through (pdf)latex" \
-	      "(use \`make latexpdf' here to do that automatically)."
-
-latexpdf: | check_python_packages
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through pdflatex..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-latexpdfja: | check_python_packages
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through platex and dvipdfmx..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-text: | check_python_packages
-	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
-	@echo
-	@echo "Build finished. The text files are in $(BUILDDIR)/text."
-
-man: | check_python_packages
-	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
-	@echo
-	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
-
-texinfo: | check_python_packages
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo
-	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
-	@echo "Run \`make' in that directory to run these through makeinfo" \
-	      "(use \`make info' here to do that automatically)."
-
-info: | check_python_packages
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo "Running Texinfo files through makeinfo..."
-	make -C $(BUILDDIR)/texinfo info
-	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
-
-gettext: | check_python_packages
-	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
-	@echo
-	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
-
-changes: | check_python_packages
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
-	@echo
-	@echo "The overview file is in $(BUILDDIR)/changes."
-
-linkcheck: | check_python_packages
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in $(BUILDDIR)/linkcheck/output.txt."
-
-gh-linkcheck: | check_python_packages
-	@echo "Checking for hardcoded GitHub links"  # note: exception for links to support policy doc as we *want* this to be a link to master's policy
-	@if (find ../ -name '*.rst' | xargs grep \
-		'https://github.com/espressif/esp-idf/tree\|https://github.com/espressif/esp-idf/blob\|https://github.com/espressif/esp-idf/raw' \
-		| grep -v 'SUPPORT_POLICY\.md' \
-		); \
-	then \
-		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_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_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_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"; \
-		exit 1; \
-	fi
-	@echo "No hardcoded links found"
-
-doctest: | check_python_packages
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."
-
-xml: | check_python_packages
-	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
-	@echo
-	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
-
-pseudoxml: | check_python_packages
-	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
-	@echo
-	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

docs/doxygen_idf.py

@@ -4,6 +4,7 @@ import os.path
 import re
 import sys
 import subprocess
+gen_dxd = __import__("gen-dxd")
 
 from local_util import copy_if_modified, call_with_python
 
@@ -18,7 +19,7 @@ def _parse_defines(header_path):
     # that these headers are all self-contained and don't include any other headers
     # not in the same directory
     print("Reading macros from %s..." % (header_path))
-    processed_output = subprocess.check_output(["xtensa-esp32-elf-gcc", "-dM", "-E", header_path])
+    processed_output = subprocess.check_output(["xtensa-esp32-elf-gcc", "-dM", "-E", header_path]).decode()
     for line in processed_output.split("\n"):
         line = line.strip()
         m = re.search("#define ([^ ]+) ?(.*)", line)
@@ -49,19 +50,27 @@ def generate_doxygen(app, project_description):
     # Call Doxygen to get XML files from the header files
     print("Calling Doxygen to generate latest XML files")
     doxy_env = {
-        "ENV_DOXYGEN_DEFINES": " ".join(defines)
+        "ENV_DOXYGEN_DEFINES": " ".join(defines),
+        "IDF_PATH": app.config.idf_path,
     }
-    subprocess.check_call(["doxygen", "../Doxyfile"], env=doxy_env)
+    doxyfile = os.path.join(app.config.docs_root, "Doxyfile")
+    # note: run Doxygen in the build directory, so the xml & xml_in files end up in there
+    subprocess.check_call(["doxygen", doxyfile], env=doxy_env, cwd=build_dir)
 
     # Doxygen has generated XML files in 'xml' directory.
     # Copy them to 'xml_in', only touching the files which have changed.
-    copy_if_modified('xml/', 'xml_in/')
+    copy_if_modified(os.path.join(build_dir, 'xml/'), os.path.join(build_dir, 'xml_in/'))
 
     # Generate 'api_name.inc' files using the XML files by Doxygen
-    call_with_python('../gen-dxd.py')
+    gen_dxd.builddir = build_dir
+    gen_dxd.doxyfile_path = doxyfile
+    gen_dxd.header_file_path_prefix = "components/"
+    gen_dxd.xml_directory_path = "{}/xml".format(build_dir)
+    gen_dxd.inc_directory_path = "{}/inc".format(build_dir)
+    gen_dxd.generate_api_inc_files()
 
     # Generate 'esp_err_defs.inc' file with ESP_ERR_ error code definitions from inc file
     esp_err_inc_path = '{}/inc/esp_err_defs.inc'.format(build_dir)
-    call_with_python('../../tools/gen_esp_err_to_name.py --rst_output ' + esp_err_inc_path + '.in')
+    call_with_python('{}/tools/gen_esp_err_to_name.py --rst_output {}.in'.format(app.config.idf_path, esp_err_inc_path))
     copy_if_modified(esp_err_inc_path + '.in', esp_err_inc_path)
 

docs/en/api-reference/bluetooth/controller_vhci.rst

@@ -18,4 +18,4 @@ Check :example:`bluetooth/bluedroid/hci` folder in ESP-IDF examples, which conta
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_bt.inc
+.. include-build-file:: inc/esp_bt.inc

docs/en/api-reference/bluetooth/esp-ble-mesh.rst

@@ -42,7 +42,7 @@ This section contains only one header file, which lists the following items of E
 * Structs used to transmit/receive messages
 * Event types and related event parameters
 
-.. include:: /_build/inc/esp_ble_mesh_defs.inc
+.. include-build-file:: inc/esp_ble_mesh_defs.inc
 
 
 ESP-BLE-MESH Core API Reference
@@ -64,37 +64,37 @@ This API reference covers six components:
 ESP-BLE-MESH Stack Initialization
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. include:: /_build/inc/esp_ble_mesh_common_api.inc
+.. include-build-file:: inc/esp_ble_mesh_common_api.inc
 
 
 Reading of Local Data Information
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. include:: /_build/inc/esp_ble_mesh_local_data_operation_api.inc
+.. include-build-file:: inc/esp_ble_mesh_local_data_operation_api.inc
 
 
 Low Power Operation (Updating)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. include:: /_build/inc/esp_ble_mesh_low_power_api.inc
+.. include-build-file:: inc/esp_ble_mesh_low_power_api.inc
 
 
 Send/Publish Messages, add Local AppKey, etc.
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. include:: /_build/inc/esp_ble_mesh_networking_api.inc
+.. include-build-file:: inc/esp_ble_mesh_networking_api.inc
 
 
 ESP-BLE-MESH Node/Provisioner Provisioning
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. include:: /_build/inc/esp_ble_mesh_provisioning_api.inc
+.. include-build-file:: inc/esp_ble_mesh_provisioning_api.inc
 
 
 ESP-BLE-MESH GATT Proxy Server
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. include:: /_build/inc/esp_ble_mesh_proxy_api.inc
+.. include-build-file:: inc/esp_ble_mesh_proxy_api.inc
 
 
 ESP-BLE-MESH Models API Reference
@@ -120,35 +120,35 @@ There are six categories of models:
 Configuration Client/Server Models
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. include:: /_build/inc/esp_ble_mesh_config_model_api.inc
+.. include-build-file:: inc/esp_ble_mesh_config_model_api.inc
 
 
 Health Client/Server Models
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. include:: /_build/inc/esp_ble_mesh_generic_model_api.inc
+.. include-build-file:: inc/esp_ble_mesh_generic_model_api.inc
 
 
 Generic Client/Server Models
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. include:: /_build/inc/esp_ble_mesh_health_model_api.inc
+.. include-build-file:: inc/esp_ble_mesh_health_model_api.inc
 
 
 Sensor Client/Server Models
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. include:: /_build/inc/esp_ble_mesh_lighting_model_api.inc
+.. include-build-file:: inc/esp_ble_mesh_lighting_model_api.inc
 
 
 Time and Scenes Client/Server Models
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. include:: /_build/inc/esp_ble_mesh_sensor_model_api.inc
+.. include-build-file:: inc/esp_ble_mesh_sensor_model_api.inc
 
 
 Lighting Client/Server Models
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. include:: /_build/inc/esp_ble_mesh_time_scene_model_api.inc
+.. include-build-file:: inc/esp_ble_mesh_time_scene_model_api.inc
 

docs/en/api-reference/bluetooth/esp_a2dp.rst

@@ -18,5 +18,5 @@ Check :example:`bluetooth/bluedroid/classic_bt` folder in ESP-IDF examples, whic
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_a2dp_api.inc
+.. include-build-file:: inc/esp_a2dp_api.inc
 

docs/en/api-reference/bluetooth/esp_avrc.rst

@@ -18,6 +18,6 @@ Application Example
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_avrc_api.inc
+.. include-build-file:: inc/esp_avrc_api.inc
 
 

docs/en/api-reference/bluetooth/esp_blufi.rst

@@ -19,5 +19,5 @@ Check :example:`bluetooth/bluedroid/ble` folder in ESP-IDF examples, which conta
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_blufi_api.inc
+.. include-build-file:: inc/esp_blufi_api.inc
 

docs/en/api-reference/bluetooth/esp_bt_defs.rst

@@ -17,5 +17,5 @@ Application Example
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_bt_defs.inc
+.. include-build-file:: inc/esp_bt_defs.inc
 

docs/en/api-reference/bluetooth/esp_bt_device.rst

@@ -18,4 +18,4 @@ Application Example
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_bt_device.inc
+.. include-build-file:: inc/esp_bt_device.inc

docs/en/api-reference/bluetooth/esp_bt_main.rst

@@ -17,6 +17,6 @@ Application Example
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_bt_main.inc
+.. include-build-file:: inc/esp_bt_main.inc
 
 

docs/en/api-reference/bluetooth/esp_gap_ble.rst

@@ -26,5 +26,5 @@ Check :example:`bluetooth/bluedroid/ble` folder in ESP-IDF examples, which conta
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_gap_ble_api.inc
+.. include-build-file:: inc/esp_gap_ble_api.inc
 

docs/en/api-reference/bluetooth/esp_gap_bt.rst

@@ -16,5 +16,5 @@ Application Example
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_gap_bt_api.inc
+.. include-build-file:: inc/esp_gap_bt_api.inc
 

docs/en/api-reference/bluetooth/esp_gatt_defs.rst

@@ -16,6 +16,6 @@ Application Example
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_gatt_defs.inc
+.. include-build-file:: inc/esp_gatt_defs.inc
 
 

docs/en/api-reference/bluetooth/esp_gattc.rst

@@ -30,5 +30,5 @@ Check :example:`bluetooth/bluedroid/ble` folder in ESP-IDF examples, which conta
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_gattc_api.inc
+.. include-build-file:: inc/esp_gattc_api.inc
 

docs/en/api-reference/bluetooth/esp_gatts.rst

@@ -30,5 +30,5 @@ Check :example:`bluetooth/bluedroid/ble` folder in ESP-IDF examples, which conta
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_gatts_api.inc
+.. include-build-file:: inc/esp_gatts_api.inc
 

docs/en/api-reference/bluetooth/esp_hf_client.rst

@@ -11,4 +11,4 @@ Overview
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_hf_client_api.inc
+.. include-build-file:: inc/esp_hf_client_api.inc

docs/en/api-reference/bluetooth/esp_hf_defs.rst

@@ -11,6 +11,6 @@ Overview
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_hf_defs.inc
+.. include-build-file:: inc/esp_hf_defs.inc
 
 

docs/en/api-reference/bluetooth/esp_spp.rst

@@ -18,5 +18,5 @@ Check :example:`bluetooth/bluedroid/classic_bt` folder in ESP-IDF examples, whic
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_spp_api.inc
+.. include-build-file:: inc/esp_spp_api.inc
 

docs/en/api-reference/bluetooth/nimble/index.rst

@@ -41,4 +41,4 @@ This documentation does not cover NimBLE APIs. Refer to `NimBLE tutorial <https:
 API Reference
 =============
 
-.. include:: /_build/inc/esp_nimble_hci.inc
+.. include-build-file:: inc/esp_nimble_hci.inc

docs/en/api-reference/error-codes.rst

@@ -5,4 +5,4 @@ This section lists various error code constants defined in ESP-IDF.
 
 For general information about error codes in ESP-IDF, see :doc:`Error Handling <../api-guides/error-handling>`.
 
-.. include:: /_build/inc/esp_err_defs.inc
+.. include-build-file:: inc/esp_err_defs.inc

docs/en/api-reference/kconfig.rst

@@ -85,7 +85,7 @@ Subsequent sections contain the list of available ESP-IDF options, automatically
 By convention, all option names are upper case with underscores. When Kconfig generates sdkconfig and sdkconfig.h files, option names are prefixed with ``CONFIG_``. So if an option ``ENABLE_FOO`` is defined in a Kconfig file and selected in menuconfig, then sdkconfig and sdkconfig.h files will have ``CONFIG_ENABLE_FOO`` defined. In this reference, option names are also prefixed with ``CONFIG_``, same as in the source code.
 
 
-.. include:: /_build/inc/kconfig.inc
+.. include-build-file:: inc/kconfig.inc
 
 Customisations
 ==============

docs/en/api-reference/network/esp_eth.rst

@@ -37,24 +37,24 @@ Ethernet PHY Common Registers
 API Reference - Driver Model
 ----------------------------
 
-.. include:: /_build/inc/esp_eth.inc
+.. include-build-file:: inc/esp_eth.inc
 
 API Reference - Common Interface
 --------------------------------
 
-.. include:: /_build/inc/esp_eth_com.inc
+.. include-build-file:: inc/esp_eth_com.inc
 
 API Reference - MAC Interface
 -----------------------------
 
-.. include:: /_build/inc/esp_eth_mac.inc
+.. include-build-file:: inc/esp_eth_mac.inc
 
 API Reference - PHY Interface
 -----------------------------
 
-.. include:: /_build/inc/esp_eth_phy.inc
+.. include-build-file:: inc/esp_eth_phy.inc
 
 API Reference - Glue for esp_netif
 ----------------------------------
 
-.. include:: /_build/inc/esp_eth_netif_glue.inc
+.. include-build-file:: inc/esp_eth_netif_glue.inc

docs/en/api-reference/network/esp_mesh.rst

@@ -332,4 +332,4 @@ ESP-IDF contains these ESP-MESH example projects:
 API Reference
 --------------
 
-.. include:: /_build/inc/esp_mesh.inc
+.. include-build-file:: inc/esp_mesh.inc

docs/en/api-reference/network/esp_netif.rst

@@ -168,10 +168,10 @@ configured with default settings, which as a consequence, means that:
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_netif.inc
+.. include-build-file:: inc/esp_netif.inc
 
 
 WiFi default API reference
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. include:: /_build/inc/esp_wifi_default.inc
+.. include-build-file:: inc/esp_wifi_default.inc

docs/en/api-reference/network/esp_netif_driver.rst

@@ -94,4 +94,4 @@ The packet data path functions for transmitting and freeing the rx buffer (defin
 the esp-netif, specifically from its TCP/IP stack connecting layer. The following API reference outlines these network stack
 interaction with the esp-netif.
 
-.. include:: /_build/inc/esp_netif_net_stack.inc
+.. include-build-file:: inc/esp_netif_net_stack.inc

docs/en/api-reference/network/esp_now.rst

@@ -84,4 +84,4 @@ Instead, post the necessary data to a queue and handle it from a lower priority
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_now.inc
+.. include-build-file:: inc/esp_now.inc

docs/en/api-reference/network/esp_smartconfig.rst

@@ -6,4 +6,4 @@ SmartConfig
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_smartconfig.inc
+.. include-build-file:: inc/esp_smartconfig.inc

docs/en/api-reference/network/esp_wifi.rst

@@ -30,7 +30,7 @@ In addition, there is a simple `esp-idf-template <https://github.com/espressif/e
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_wifi.inc
+.. include-build-file:: inc/esp_wifi.inc
-.. include:: /_build/inc/esp_wifi_types.inc
+.. include-build-file:: inc/esp_wifi_types.inc
 
 

docs/en/api-reference/peripherals/adc.rst

@@ -224,18 +224,18 @@ This reference covers three components:
 ADC driver
 ^^^^^^^^^^
 
-.. include:: /_build/inc/adc.inc
+.. include-build-file:: inc/adc.inc
 
 .. _adc-api-reference-adc-calibration:
 
 ADC Calibration
 ^^^^^^^^^^^^^^^
 
-.. include:: /_build/inc/esp_adc_cal.inc
+.. include-build-file:: inc/esp_adc_cal.inc
 
 .. _adc-api-reference-gpio-lookup-macros:
 
 GPIO Lookup Macros
 ^^^^^^^^^^^^^^^^^^
 
-.. include:: /_build/inc/adc_channel.inc
+.. include-build-file:: inc/adc_channel.inc

docs/en/api-reference/peripherals/can.rst

@@ -485,5 +485,5 @@ Application Examples
 API Reference
 -------------
 
-.. include:: /_build/inc/can_types.inc
+.. include-build-file:: inc/can_types.inc
-.. include:: /_build/inc/can.inc
+.. include-build-file:: inc/can.inc

docs/en/api-reference/peripherals/dac.rst

@@ -28,7 +28,7 @@ Setting DAC channel 1 (GPIO 25) voltage to approx 0.78 of VDD_A voltage (VDD * 2
 API Reference
 -------------
 
-.. include:: /_build/inc/dac.inc
+.. include-build-file:: inc/dac.inc
 
 GPIO Lookup Macros
 ^^^^^^^^^^^^^^^^^^
@@ -38,4 +38,4 @@ e.g.
 1. ``DAC_CHANNEL_1_GPIO_NUM`` is the GPIO number of channel 1 (25);
 2. ``DAC_GPIO26_CHANNEL`` is the channel number of GPIO 26 (channel 2).
 
-.. include:: /_build/inc/dac_channel.inc
+.. include-build-file:: inc/dac_channel.inc

docs/en/api-reference/peripherals/gpio.rst

@@ -19,10 +19,10 @@ GPIO output and input interrupt example: :example:`peripherals/gpio`.
 API Reference - Normal GPIO
 ---------------------------
 
-.. include:: /_build/inc/gpio.inc
+.. include-build-file:: inc/gpio.inc
 
 API Reference - RTC GPIO
 ------------------------
 
-.. include:: /_build/inc/rtc_io.inc
+.. include-build-file:: inc/rtc_io.inc
 

docs/en/api-reference/peripherals/i2c.rst

@@ -249,4 +249,4 @@ I2C master and slave example: :example:`peripherals/i2c`.
 API Reference
 -------------
 
-.. include:: /_build/inc/i2c.inc
+.. include-build-file:: inc/i2c.inc

docs/en/api-reference/peripherals/i2s.rst

@@ -208,5 +208,5 @@ Configuring I2S to use internal DAC for analog output
 API Reference
 -------------
 
-.. include:: /_build/inc/i2s.inc
+.. include-build-file:: inc/i2s.inc
 

docs/en/api-reference/peripherals/ledc.rst

@@ -175,5 +175,5 @@ The LEDC change duty cycle and fading control example: :example:`peripherals/led
 API Reference
 -------------
 
-.. include:: /_build/inc/ledc.inc
+.. include-build-file:: inc/ledc.inc
 

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

@@ -175,6 +175,7 @@ Examples of using MCPWM for motor control: :example:`peripherals/mcpwm`:
 API Reference
 -------------
 
-.. include:: /_build/inc/mcpwm_types.inc
+.. include-build-file:: inc/mcpwm_types.inc
-.. include:: /_build/inc/mcpwm.inc
+.. include-build-file:: inc/mcpwm.inc
+
 

docs/en/api-reference/peripherals/pcnt.rst

@@ -92,5 +92,5 @@ Pulse counter with control signal and event interrupt example: :example:`periphe
 API Reference
 -------------
 
-.. include:: /_build/inc/pcnt.inc
+.. include-build-file:: inc/pcnt.inc
 

docs/en/api-reference/peripherals/rmt.rst

@@ -264,5 +264,5 @@ Application Examples
 API Reference
 -------------
 
-.. include:: /_build/inc/rmt.inc
+.. include-build-file:: inc/rmt.inc
 

docs/en/api-reference/peripherals/sdio_slave.rst

@@ -277,6 +277,7 @@ Slave/master communication: :example:`peripherals/sdio`.
 API Reference
 -------------
 
-.. include:: /_build/inc/sdio_slave_types.inc
+.. include-build-file:: inc/sdio_slave_types.inc
-.. include:: /_build/inc/sdio_slave.inc
+.. include-build-file:: inc/sdio_slave.inc
+
 

docs/en/api-reference/peripherals/sdmmc_host.rst

@@ -106,4 +106,4 @@ See :doc:`sd_pullup_requirements` for pullup support and compatibilities of modu
 API Reference
 -------------
 
-.. include:: /_build/inc/sdmmc_host.inc
+.. include-build-file:: inc/sdmmc_host.inc

docs/en/api-reference/peripherals/sdspi_host.rst

@@ -47,4 +47,4 @@ Other functions are mostly used by the protocol level SD/SDIO/MMC driver via fun
 API Reference
 -------------
 
-.. include:: /_build/inc/sdspi_host.inc
+.. include-build-file:: inc/sdspi_host.inc

docs/en/api-reference/peripherals/sigmadelta.rst

@@ -29,4 +29,4 @@ Sigma-delta Modulation example: :example:`peripherals/sigmadelta`.
 API Reference
 -------------
 
-.. include:: /_build/inc/sigmadelta.inc
+.. include-build-file:: inc/sigmadelta.inc

docs/en/api-reference/peripherals/spi_master.rst

@@ -455,12 +455,12 @@ The code example for displaying graphics on an ESP32-WROVER-KIT's 320x240 LCD sc
 API Reference - SPI Common
 --------------------------
 
-.. include:: /_build/inc/spi_types.inc
+.. include-build-file:: inc/spi_types.inc
-.. include:: /_build/inc/spi_common.inc
+.. include-build-file:: inc/spi_common.inc
 
 
 API Reference - SPI Master
 --------------------------
 
-.. include:: /_build/inc/spi_master.inc
+.. include-build-file:: inc/spi_master.inc
 

docs/en/api-reference/peripherals/spi_slave.rst

@@ -191,5 +191,5 @@ The code example for Device/Host communication can be found in the :example:`per
 API Reference
 -------------
 
-.. include:: /_build/inc/spi_slave.inc
+.. include-build-file:: inc/spi_slave.inc
 

docs/en/api-reference/peripherals/temp_sensor.rst

@@ -29,4 +29,4 @@ Temperature sensor reading example: :example:`peripherals/temp_sensor`.
 API Reference - Normal Temp Sensor
 ----------------------------------
 
-.. include:: /_build/inc/temp_sensor.inc
+.. include-build-file:: inc/temp_sensor.inc

docs/en/api-reference/peripherals/timer.rst

@@ -106,4 +106,4 @@ The 64-bit hardware timer example: :example:`peripherals/timer_group`.
 API Reference
 -------------
 
-.. include:: /_build/inc/timer.inc
+.. include-build-file:: inc/timer.inc

docs/en/api-reference/peripherals/touch_pad.rst

@@ -162,7 +162,7 @@ Application Examples
 API Reference
 -------------
 
-.. include:: /_build/inc/touch_pad.inc
+.. include-build-file:: inc/touch_pad.inc
 
 GPIO Lookup Macros
 ^^^^^^^^^^^^^^^^^^
@@ -172,5 +172,5 @@ e.g.
 1. ``TOUCH_PAD_NUM5_GPIO_NUM`` is the GPIO number of channel 5 (12);
 2. ``TOUCH_PAD_GPIO4_CHANNEL`` is the channel number of GPIO 4 (channel 0).
 
-.. include:: /_build/inc/touch_sensor_channel.inc
+.. include-build-file:: inc/touch_sensor_channel.inc
-.. include:: /_build/inc/touch_sensor_types.inc
+.. include-build-file:: inc/touch_sensor_types.inc

docs/en/api-reference/peripherals/uart.rst

@@ -379,7 +379,7 @@ The table below describes the code examples available in the directory :example:
 API Reference
 -------------
 
-.. include:: /_build/inc/uart.inc
+.. include-build-file:: inc/uart.inc
 
 
 GPIO Lookup Macros
@@ -395,5 +395,5 @@ The UART peripherals have dedicated IO_MUX pins to which they are connected dire
 2. :c:macro:`UART_GPIO19_DIRECT_CHANNEL` returns the UART number of GPIO 19 when connected to the UART peripheral via IO_MUX (this is UART_NUM_0)
 3. :c:macro:`UART_CTS_GPIO19_DIRECT_CHANNEL` returns the UART number of GPIO 19 when used as the UART CTS pin via IO_MUX (this is UART_NUM_0). Similar to the above macro but specifies the pin function which is also part of the IO_MUX assignment.
 
-.. include:: /_build/inc/uart_channel.inc
+.. include-build-file:: inc/uart_channel.inc
 

docs/en/api-reference/protocols/esp_http_client.rst

@@ -188,4 +188,4 @@ HTTP Client example: :example:`protocols/esp_http_client`.
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_http_client.inc
+.. include-build-file:: inc/esp_http_client.inc

docs/en/api-reference/protocols/esp_http_server.rst

@@ -155,4 +155,4 @@ Check the example under :example:`protocols/http_server/persistent_sockets`.
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_http_server.inc
+.. include-build-file:: inc/esp_http_server.inc

docs/en/api-reference/protocols/esp_https_server.rst

@@ -47,4 +47,4 @@ The initial session setup can take about two seconds, or more with slower clock
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_https_server.inc
+.. include-build-file:: inc/esp_https_server.inc

docs/en/api-reference/protocols/esp_local_ctrl.rst

@@ -203,4 +203,4 @@ The various protocomm endpoints provided by **esp_local_ctrl** are listed below:
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_local_ctrl.inc
+.. include-build-file:: inc/esp_local_ctrl.inc

docs/en/api-reference/protocols/esp_serial_slave_link.rst

@@ -150,5 +150,5 @@ Please refer to the specific example README.md for details.
 API Reference
 -------------
 
-.. include:: /_build/inc/essl.inc
+.. include-build-file:: inc/essl.inc
-.. include:: /_build/inc/essl_sdio.inc
+.. include-build-file:: inc/essl_sdio.inc

docs/en/api-reference/protocols/esp_tls.rst

@@ -91,4 +91,4 @@ SSL/TLS libraries and with all respective configurations set to default.
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_tls.inc
+.. include-build-file:: inc/esp_tls.inc

docs/en/api-reference/protocols/esp_websocket_client.rst

@@ -66,5 +66,5 @@ Simple WebSocket example that uses esp_websocket_client to establish a websocket
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_websocket_client.inc
+.. include-build-file:: inc/esp_websocket_client.inc
 

docs/en/api-reference/protocols/icmp_echo.rst

@@ -117,6 +117,6 @@ ICMP echo example: :example:`protocols/icmp_echo`
 API Reference
 -------------
 
-.. include:: /_build/inc/ping_sock.inc
+.. include-build-file:: inc/ping_sock.inc
 
 

docs/en/api-reference/protocols/mdns.rst

@@ -184,6 +184,6 @@ mDNS server/scanner example: :example:`protocols/mdns`.
 API Reference
 -------------
 
-.. include:: /_build/inc/mdns.inc
+.. include-build-file:: inc/mdns.inc
 
 

docs/en/api-reference/protocols/mqtt.rst

@@ -158,4 +158,4 @@ The following events may be posted by the MQTT client:
 API Reference
 -------------
 
-.. include:: /_build/inc/mqtt_client.inc
+.. include-build-file:: inc/mqtt_client.inc

docs/en/api-reference/provisioning/protocomm.rst

@@ -166,9 +166,9 @@ For complete example see :example:`provisioning/ble_prov`
 API Reference
 -------------
 
-.. include:: /_build/inc/protocomm.inc
+.. include-build-file:: inc/protocomm.inc
-.. include:: /_build/inc/protocomm_security.inc
+.. include-build-file:: inc/protocomm_security.inc
-.. include:: /_build/inc/protocomm_security0.inc
+.. include-build-file:: inc/protocomm_security0.inc
-.. include:: /_build/inc/protocomm_security1.inc
+.. include-build-file:: inc/protocomm_security1.inc
-.. include:: /_build/inc/protocomm_httpd.inc
+.. include-build-file:: inc/protocomm_httpd.inc
-.. include:: /_build/inc/protocomm_ble.inc
+.. include-build-file:: inc/protocomm_ble.inc

docs/en/api-reference/provisioning/wifi_provisioning.rst

@@ -279,8 +279,8 @@ For complete example implementation see :example:`provisioning/manager`
 API Reference
 -------------
 
-.. include:: /_build/inc/manager.inc
+.. include-build-file:: inc/manager.inc
-.. include:: /_build/inc/scheme_ble.inc
+.. include-build-file:: inc/scheme_ble.inc
-.. include:: /_build/inc/scheme_softap.inc
+.. include-build-file:: inc/scheme_softap.inc
-.. include:: /_build/inc/scheme_console.inc
+.. include-build-file:: inc/scheme_console.inc
-.. include:: /_build/inc/wifi_config.inc
+.. include-build-file:: inc/wifi_config.inc

docs/en/api-reference/storage/nvs_flash.rst

@@ -31,8 +31,8 @@ You can find two code examples in the :example:`storage` directory of ESP-IDF ex
 API Reference
 -------------
 
-.. include:: /_build/inc/nvs_flash.inc
+.. include-build-file:: inc/nvs_flash.inc
 
-.. include:: /_build/inc/nvs.inc
+.. include-build-file:: inc/nvs.inc
 
 

docs/en/api-reference/storage/sdmmc.rst

@@ -100,6 +100,6 @@ Most applications need to use the protocol layer only in one task. For this reas
 API Reference
 -------------
 
-.. include:: /_build/inc/sdmmc_cmd.inc
+.. include-build-file:: inc/sdmmc_cmd.inc
 
-.. include:: /_build/inc/sdmmc_types.inc
+.. include-build-file:: inc/sdmmc_types.inc

docs/en/api-reference/storage/spi_flash.rst

@@ -31,18 +31,18 @@ In a single core environment (:ref:`CONFIG_FREERTOS_UNICORE` enabled), you need
 API Reference - SPI Flash
 -------------------------
 
-.. include:: /_build/inc/esp_flash_spi_init.inc
+.. include-build-file:: inc/esp_flash_spi_init.inc
-.. include:: /_build/inc/esp_flash.inc
+.. include-build-file:: inc/esp_flash.inc
-.. include:: /_build/inc/spi_flash_types.inc
+.. include-build-file:: inc/spi_flash_types.inc
 
 API Reference - Partition Table
 -------------------------------
 
-.. include:: /_build/inc/esp_partition.inc
+.. include-build-file:: inc/esp_partition.inc
 
 API Reference - Flash Encrypt
 -----------------------------
 
-.. include:: /_build/inc/esp_flash_encrypt.inc
+.. include-build-file:: inc/esp_flash_encrypt.inc
 
 

docs/en/api-reference/storage/spiffs.rst

@@ -145,4 +145,4 @@ An example of using SPIFFS is provided in the :example:`storage/spiffs` director
 High-level API Reference
 ------------------------
 
-.. include:: /_build/inc/esp_spiffs.inc
+.. include-build-file:: inc/esp_spiffs.inc

docs/en/api-reference/storage/vfs.rst

@@ -10,7 +10,7 @@ Application Example
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_vfs.inc
+.. include-build-file:: inc/esp_vfs.inc
 
-.. include:: /_build/inc/esp_vfs_dev.inc
+.. include-build-file:: inc/esp_vfs_dev.inc
 

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

@@ -30,5 +30,5 @@ Functions
 Mid level API Reference
 -----------------------
 
-.. include:: /_build/inc/wear_levelling.inc
+.. include-build-file:: inc/wear_levelling.inc
 

docs/en/api-reference/system/app_image_format.rst

@@ -103,6 +103,6 @@ To guarantee that the custom structure is located in the image even if it is not
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_app_format.inc
+.. include-build-file:: inc/esp_app_format.inc
 
 

docs/en/api-reference/system/app_trace.rst

@@ -14,6 +14,6 @@ Developers can use this library to send application specific state of execution
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_app_trace.inc
+.. include-build-file:: inc/esp_app_trace.inc
-.. include:: /_build/inc/esp_sysview_trace.inc
+.. include-build-file:: inc/esp_sysview_trace.inc
 

docs/en/api-reference/system/efuse.rst

@@ -341,4 +341,4 @@ To get a dump for all eFuse registers.
 	00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
 
 
-.. include:: /_build/inc/esp_efuse.inc
+.. include-build-file:: inc/esp_efuse.inc

docs/en/api-reference/system/esp_err.rst

@@ -10,5 +10,5 @@ For the full list of error codes defined in ESP-IDF, see :doc:`Error Code Refere
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_err.inc
+.. include-build-file:: inc/esp_err.inc
 

docs/en/api-reference/system/esp_event.rst

@@ -216,8 +216,8 @@ Other examples which also adopt esp_event library:
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_event.inc
+.. include-build-file:: inc/esp_event.inc
-.. include:: /_build/inc/esp_event_base.inc
+.. include-build-file:: inc/esp_event_base.inc
 
 Related Documents
 -----------------

docs/en/api-reference/system/esp_event_legacy.rst

@@ -4,4 +4,4 @@ Legacy event loop
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_event_legacy.inc
+.. include-build-file:: inc/esp_event_legacy.inc

docs/en/api-reference/system/esp_expression_with_stack.rst

@@ -51,6 +51,6 @@ The usage may looks like the code below:
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_expression_with_stack.inc
+.. include-build-file:: inc/esp_expression_with_stack.inc
 
 

docs/en/api-reference/system/esp_https_ota.rst

@@ -37,4 +37,4 @@ For additional security, signature of OTA firmware images can be verified. For t
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_https_ota.inc
+.. include-build-file:: inc/esp_https_ota.inc

docs/en/api-reference/system/esp_pthread.rst

@@ -68,5 +68,5 @@ The API can also be used for inheriting the settings across threads. For example
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_pthread.inc
+.. include-build-file:: inc/esp_pthread.inc
 

docs/en/api-reference/system/esp_timer.rst

@@ -66,6 +66,6 @@ The following example illustrates usage of ``esp_timer`` APIs: :example:`system/
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_timer.inc
+.. include-build-file:: inc/esp_timer.inc
 
 

docs/en/api-reference/system/freertos.rst

@@ -13,27 +13,27 @@ and :doc:`ESP-IDF FreeRTOS Additions<freertos_additions>`.
 Task API
 --------
 
-.. include:: /_build/inc/task.inc
+.. include-build-file:: inc/task.inc
 
 Queue API
 ---------
 
-.. include:: /_build/inc/queue.inc
+.. include-build-file:: inc/queue.inc
 
 Semaphore API
 -------------
 
-.. include:: /_build/inc/semphr.inc
+.. include-build-file:: inc/semphr.inc
 
 Timer API
 ---------
 
-.. include:: /_build/inc/timers.inc
+.. include-build-file:: inc/timers.inc
 
 
 Event Group API
 ---------------
 
-.. include:: /_build/inc/event_groups.inc
+.. include-build-file:: inc/event_groups.inc
 
 

docs/en/api-reference/system/freertos_additions.rst

@@ -469,7 +469,7 @@ Ring Buffer API Reference
     of tasks using the ring buffer simultaneously is low, and the ring buffer is not operating
     near maximum capacity.
 
-.. include:: /_build/inc/ringbuf.inc
+.. include-build-file:: inc/ringbuf.inc
 
 
 .. _hooks:
@@ -518,4 +518,4 @@ in turn.
 Hooks API Reference
 -------------------
 
-.. include:: /_build/inc/esp_freertos_hooks.inc
+.. include-build-file:: inc/esp_freertos_hooks.inc

docs/en/api-reference/system/heap_debug.rst

@@ -402,4 +402,4 @@ One way to differentiate between "real" and "false positive" memory leaks is to
 API Reference - Heap Tracing
 ----------------------------
 
-.. include:: /_build/inc/esp_heap_trace.inc
+.. include-build-file:: inc/esp_heap_trace.inc

docs/en/api-reference/system/himem.rst

@@ -30,4 +30,4 @@ An example doing a simple memory test of the high memory range is available in e
 API Reference
 -------------
 
-.. include:: /_build/inc/himem.inc
+.. include-build-file:: inc/himem.inc

docs/en/api-reference/system/intr_alloc.rst

@@ -100,6 +100,6 @@ or the status should be handled in other enabled interrupt properly**. You may l
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_intr_alloc.inc
+.. include-build-file:: inc/esp_intr_alloc.inc
 
 

docs/en/api-reference/system/ipc.rst

@@ -38,6 +38,6 @@ IPC, especially when attempting to take a mutex within the function.
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_ipc.inc
+.. include-build-file:: inc/esp_ipc.inc
 
 

docs/en/api-reference/system/log.rst

@@ -12,7 +12,7 @@ The logging library is commonly used by most esp-idf components and examples. Fo
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_log.inc
+.. include-build-file:: inc/esp_log.inc
 
 
 

docs/en/api-reference/system/mem_alloc.rst

@@ -111,7 +111,7 @@ To use the region above the 4MiB limit, you can use the :doc:`himem API</api-ref
 API Reference - Heap Allocation
 -------------------------------
 
-.. include:: /_build/inc/esp_heap_caps.inc
+.. include-build-file:: inc/esp_heap_caps.inc
 
 Thread Safety
 ^^^^^^^^^^^^^
@@ -132,7 +132,7 @@ The following features are documented on the :doc:`Heap Memory Debugging </api-r
 API Reference - Initialisation
 ------------------------------
 
-.. include:: /_build/inc/esp_heap_caps_init.inc
+.. include-build-file:: inc/esp_heap_caps_init.inc
 
 Implementation Notes
 --------------------
@@ -150,4 +150,4 @@ API Reference - Multi Heap API
 
 (Note: The multi heap API is used internally by the heap capabilities allocator. Most IDF programs will never need to call this API directly.)
 
-.. include:: /_build/inc/multi_heap.inc
+.. include-build-file:: inc/multi_heap.inc

docs/en/api-reference/system/ota.rst

@@ -311,7 +311,7 @@ End-to-end example of OTA firmware update workflow: :example:`system/ota`.
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_ota_ops.inc
+.. include-build-file:: inc/esp_ota_ops.inc
 
 
 

docs/en/api-reference/system/perfmon.rst

@@ -21,6 +21,6 @@ Header Files
 API Reference
 -------------
 
-.. include:: /_build/inc/xtensa_perfmon_access.inc
+.. include-build-file:: inc/xtensa_perfmon_access.inc
-.. include:: /_build/inc/xtensa_perfmon_apis.inc
+.. include-build-file:: inc/xtensa_perfmon_apis.inc
 

docs/en/api-reference/system/power_management.rst

@@ -141,6 +141,6 @@ The following peripheral drivers are not aware of DFS yet. Applications need to
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_pm.inc
+.. include-build-file:: inc/esp_pm.inc
-.. include:: /_build/inc/pm.inc
+.. include-build-file:: inc/pm.inc
 

docs/en/api-reference/system/sleep_modes.rst

@@ -163,6 +163,6 @@ More extensive example in :example:`system/deep_sleep` illustrates usage of vari
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_sleep.inc
+.. include-build-file:: inc/esp_sleep.inc
 
 

docs/en/api-reference/system/system.rst

@@ -162,7 +162,7 @@ If :ref:`CONFIG_APP_PROJECT_VER_FROM_CONFIG` option is set, the value of :ref:`C
 API Reference
 -------------
 
-.. include:: /_build/inc/esp_system.inc
+.. include-build-file:: inc/esp_system.inc
-.. include:: /_build/inc/esp_idf_version.inc
+.. include-build-file:: inc/esp_idf_version.inc
 
 

docs/en/api-reference/system/wdts.rst

@@ -102,4 +102,4 @@ Task Watchdog API Reference
 
 A full example using the Task Watchdog is available in esp-idf: :example:`system/task_watchdog`
 
-.. include:: /_build/inc/esp_task_wdt.inc
+.. include-build-file:: inc/esp_task_wdt.inc

docs/en/api-reference/template.rst

@@ -75,7 +75,7 @@ API Reference
 
     5. To show contents of ``*.inc`` file in documentation, include it as follows::
 
-       .. include:: /_build/inc/esp_wifi.inc
+       .. include-build-file:: inc/esp_wifi.inc
 
        For example see :idf_file:`docs/en/api-reference/wifi/esp_wifi.rst`
     

docs/en/get-started-legacy/index.rst

@@ -10,7 +10,7 @@ This document is intended to help you set up the software development environmen
 
 After that, a simple example will show you how to use ESP-IDF (Espressif IoT Development Framework) for menu configuration, then how to build and flash firmware onto an ESP32 board.
 
-.. include:: /_build/inc/version-note.inc
+.. include-build-file:: inc/version-note.inc
 
 Introduction
 ============
@@ -142,13 +142,13 @@ To get a local copy of ESP-IDF, navigate to your installation directory and clon
 
 Open Terminal, and run the following commands:
 
-.. include:: /_build/inc/git-clone-bash.inc
+.. include-build-file:: inc/git-clone-bash.inc
 
 ESP-IDF will be downloaded into ``~/esp/esp-idf``.
 
 Consult :doc:`/versions` for information about which ESP-IDF version to use in a given situation.
 
-.. include:: /_build/inc/git-clone-notes.inc
+.. include-build-file:: inc/git-clone-notes.inc
 
 .. note::
 

docs/en/get-started-legacy/linux-setup-scratch.rst

@@ -60,7 +60,7 @@ Create the working directory and go into it::
 
 Download ``crosstool-NG`` and build it:
 
-.. include:: /_build/inc/scratch-build-code.inc
+.. include-build-file:: inc/scratch-build-code.inc
 
 Build the toolchain::
 

docs/en/get-started-legacy/linux-setup.rst

@@ -29,7 +29,7 @@ To compile with ESP-IDF you need to get the following packages:
 Toolchain Setup
 ===============
 
-.. include:: /_build/inc/download-links.inc
+.. include-build-file:: inc/download-links.inc
 
 ESP32 toolchain for Linux is available for download from Espressif website:
 
@@ -45,11 +45,11 @@ ESP32 toolchain for Linux is available for download from Espressif website:
 
     - for 64-bit Linux:
 
-      .. include:: /_build/inc/unpack-code-linux64.inc
+      .. include-build-file:: inc/unpack-code-linux64.inc
 
     - for 32-bit Linux:
 
-      .. include:: /_build/inc/unpack-code-linux32.inc
+      .. include-build-file:: inc/unpack-code-linux32.inc
 
 .. _setup-linux-toolchain-add-it-to-path-legacy:
 

docs/en/get-started-legacy/macos-setup-scratch.rst

@@ -57,7 +57,7 @@ Go into the newly created directory::
 
 Download ``crosstool-NG`` and build it:
 
-.. include:: /_build/inc/scratch-build-code.inc
+.. include-build-file:: inc/scratch-build-code.inc
 
 Build the toolchain::
 

docs/en/get-started-legacy/macos-setup.rst

@@ -19,7 +19,7 @@ Install Prerequisites
 Toolchain Setup
 ===============
 
-.. include:: /_build/inc/download-links.inc
+.. include-build-file:: inc/download-links.inc
 
 ESP32 toolchain for macOS is available for download from Espressif website:
 
@@ -27,7 +27,7 @@ ESP32 toolchain for macOS is available for download from Espressif website:
 
 Download this file, then extract it in ``~/esp`` directory:
 
-.. include:: /_build/inc/unpack-code-osx.inc
+.. include-build-file:: inc/unpack-code-osx.inc
 
 .. _setup-macos-toolchain-add-it-to-path-legacy:
 

docs/en/get-started-legacy/windows-setup-scratch.rst

@@ -78,7 +78,7 @@ Add this line to ``/etc/profile`` in the MSYS directory in order to permanently
 Alternative Setup: Just download a toolchain
 ============================================
 
-.. include:: /_build/inc/download-links.inc
+.. include-build-file:: inc/download-links.inc
 
 If you already have an MSYS2 install or want to do things differently, you can download just the toolchain here: