From e6211c7864505f3a66687b402faeb06fa7377f25 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Wed, 13 Nov 2019 11:46:16 +0800 Subject: [PATCH] docs: add new top-level docs builder that builds docs for a single chip --- docs/Doxyfile | 356 +++++++++--------- docs/build_docs.py | 89 +++++ docs/conf_common.py | 32 +- docs/docs_common.mk | 217 ----------- docs/doxygen_idf.py | 21 +- .../bluetooth/controller_vhci.rst | 2 +- .../api-reference/bluetooth/esp-ble-mesh.rst | 26 +- docs/en/api-reference/bluetooth/esp_a2dp.rst | 2 +- docs/en/api-reference/bluetooth/esp_avrc.rst | 2 +- docs/en/api-reference/bluetooth/esp_blufi.rst | 2 +- .../api-reference/bluetooth/esp_bt_defs.rst | 2 +- .../api-reference/bluetooth/esp_bt_device.rst | 2 +- .../api-reference/bluetooth/esp_bt_main.rst | 2 +- .../api-reference/bluetooth/esp_gap_ble.rst | 2 +- .../en/api-reference/bluetooth/esp_gap_bt.rst | 2 +- .../api-reference/bluetooth/esp_gatt_defs.rst | 2 +- docs/en/api-reference/bluetooth/esp_gattc.rst | 2 +- docs/en/api-reference/bluetooth/esp_gatts.rst | 2 +- .../api-reference/bluetooth/esp_hf_client.rst | 2 +- .../api-reference/bluetooth/esp_hf_defs.rst | 2 +- docs/en/api-reference/bluetooth/esp_spp.rst | 2 +- .../api-reference/bluetooth/nimble/index.rst | 2 +- docs/en/api-reference/error-codes.rst | 2 +- docs/en/api-reference/kconfig.rst | 2 +- docs/en/api-reference/network/esp_eth.rst | 10 +- docs/en/api-reference/network/esp_mesh.rst | 2 +- docs/en/api-reference/network/esp_netif.rst | 4 +- .../network/esp_netif_driver.rst | 2 +- docs/en/api-reference/network/esp_now.rst | 2 +- .../api-reference/network/esp_smartconfig.rst | 2 +- docs/en/api-reference/network/esp_wifi.rst | 4 +- docs/en/api-reference/peripherals/adc.rst | 6 +- docs/en/api-reference/peripherals/can.rst | 4 +- docs/en/api-reference/peripherals/dac.rst | 4 +- docs/en/api-reference/peripherals/gpio.rst | 4 +- docs/en/api-reference/peripherals/i2c.rst | 2 +- docs/en/api-reference/peripherals/i2s.rst | 2 +- docs/en/api-reference/peripherals/ledc.rst | 2 +- docs/en/api-reference/peripherals/mcpwm.rst | 5 +- docs/en/api-reference/peripherals/pcnt.rst | 2 +- docs/en/api-reference/peripherals/rmt.rst | 2 +- .../api-reference/peripherals/sdio_slave.rst | 5 +- .../api-reference/peripherals/sdmmc_host.rst | 2 +- .../api-reference/peripherals/sdspi_host.rst | 2 +- .../api-reference/peripherals/sigmadelta.rst | 2 +- .../api-reference/peripherals/spi_master.rst | 6 +- .../api-reference/peripherals/spi_slave.rst | 2 +- .../api-reference/peripherals/temp_sensor.rst | 2 +- docs/en/api-reference/peripherals/timer.rst | 2 +- .../api-reference/peripherals/touch_pad.rst | 6 +- docs/en/api-reference/peripherals/uart.rst | 4 +- .../protocols/esp_http_client.rst | 2 +- .../protocols/esp_http_server.rst | 2 +- .../protocols/esp_https_server.rst | 2 +- .../protocols/esp_local_ctrl.rst | 2 +- .../protocols/esp_serial_slave_link.rst | 4 +- docs/en/api-reference/protocols/esp_tls.rst | 2 +- .../protocols/esp_websocket_client.rst | 2 +- docs/en/api-reference/protocols/icmp_echo.rst | 2 +- docs/en/api-reference/protocols/mdns.rst | 2 +- docs/en/api-reference/protocols/mqtt.rst | 2 +- .../api-reference/provisioning/protocomm.rst | 12 +- .../provisioning/wifi_provisioning.rst | 10 +- docs/en/api-reference/storage/nvs_flash.rst | 4 +- docs/en/api-reference/storage/sdmmc.rst | 4 +- docs/en/api-reference/storage/spi_flash.rst | 10 +- docs/en/api-reference/storage/spiffs.rst | 2 +- docs/en/api-reference/storage/vfs.rst | 4 +- .../api-reference/storage/wear-levelling.rst | 2 +- .../api-reference/system/app_image_format.rst | 2 +- docs/en/api-reference/system/app_trace.rst | 4 +- docs/en/api-reference/system/efuse.rst | 2 +- docs/en/api-reference/system/esp_err.rst | 2 +- docs/en/api-reference/system/esp_event.rst | 4 +- .../api-reference/system/esp_event_legacy.rst | 2 +- .../system/esp_expression_with_stack.rst | 2 +- .../en/api-reference/system/esp_https_ota.rst | 2 +- docs/en/api-reference/system/esp_pthread.rst | 2 +- docs/en/api-reference/system/esp_timer.rst | 2 +- docs/en/api-reference/system/freertos.rst | 10 +- .../system/freertos_additions.rst | 4 +- docs/en/api-reference/system/heap_debug.rst | 2 +- docs/en/api-reference/system/himem.rst | 2 +- docs/en/api-reference/system/intr_alloc.rst | 2 +- docs/en/api-reference/system/ipc.rst | 2 +- docs/en/api-reference/system/log.rst | 2 +- docs/en/api-reference/system/mem_alloc.rst | 6 +- docs/en/api-reference/system/ota.rst | 2 +- docs/en/api-reference/system/perfmon.rst | 4 +- .../api-reference/system/power_management.rst | 4 +- docs/en/api-reference/system/sleep_modes.rst | 2 +- docs/en/api-reference/system/system.rst | 4 +- docs/en/api-reference/system/wdts.rst | 2 +- docs/en/api-reference/template.rst | 2 +- docs/en/get-started-legacy/index.rst | 6 +- .../linux-setup-scratch.rst | 2 +- docs/en/get-started-legacy/linux-setup.rst | 6 +- .../macos-setup-scratch.rst | 2 +- docs/en/get-started-legacy/macos-setup.rst | 4 +- .../windows-setup-scratch.rst | 2 +- docs/en/get-started/index.rst | 4 +- docs/en/get-started/linux-setup-scratch.rst | 2 +- docs/en/get-started/macos-setup-scratch.rst | 2 +- docs/en/get-started/windows-setup-scratch.rst | 6 +- docs/gen-dxd.py | 6 +- docs/idf_build_system/__init__.py | 15 +- docs/include_build_file.py | 18 + docs/kconfig_reference.py | 17 +- docs/zh_CN/api-reference/network/esp_eth.rst | 10 +- .../api-reference/network/esp_smartconfig.rst | 2 +- docs/zh_CN/api-reference/network/esp_wifi.rst | 4 +- .../zh_CN/api-reference/peripherals/timer.rst | 2 +- .../api-reference/peripherals/touch_pad.rst | 6 +- .../protocols/esp_http_server.rst | 2 +- docs/zh_CN/api-reference/protocols/mdns.rst | 2 +- .../zh_CN/api-reference/storage/nvs_flash.rst | 4 +- docs/zh_CN/api-reference/storage/sdmmc.rst | 4 +- .../zh_CN/api-reference/storage/spi_flash.rst | 10 +- docs/zh_CN/api-reference/storage/spiffs.rst | 2 +- docs/zh_CN/api-reference/storage/vfs.rst | 4 +- .../api-reference/storage/wear-levelling.rst | 2 +- .../api-reference/system/power_management.rst | 4 +- docs/zh_CN/get-started-legacy/index.rst | 6 +- .../linux-setup-scratch.rst | 2 +- docs/zh_CN/get-started-legacy/linux-setup.rst | 6 +- .../macos-setup-scratch.rst | 2 +- docs/zh_CN/get-started-legacy/macos-setup.rst | 4 +- .../windows-setup-scratch.rst | 2 +- docs/zh_CN/get-started/index.rst | 4 +- .../zh_CN/get-started/linux-setup-scratch.rst | 2 +- .../zh_CN/get-started/macos-setup-scratch.rst | 2 +- .../get-started/windows-setup-scratch.rst | 6 +- tools/ci/executable-list.txt | 4 +- 133 files changed, 566 insertions(+), 637 deletions(-) create mode 100755 docs/build_docs.py delete mode 100644 docs/docs_common.mk create mode 100644 docs/include_build_file.py diff --git a/docs/Doxyfile b/docs/Doxyfile index 5755d335a0..823959f2a3 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -24,270 +24,270 @@ INPUT = \ ## ## Wi-Fi - API Reference ## - ../../components/esp_wifi/include/esp_wifi.h \ - ../../components/esp_wifi/include/esp_wifi_types.h \ - ../../components/esp_wifi/include/esp_smartconfig.h \ - ../../components/esp_wifi/include/esp_now.h \ - ../../components/esp_wifi/include/esp_wifi_default.h \ + $(IDF_PATH)/components/esp_wifi/include/esp_wifi.h \ + $(IDF_PATH)/components/esp_wifi/include/esp_wifi_types.h \ + $(IDF_PATH)/components/esp_wifi/include/esp_smartconfig.h \ + $(IDF_PATH)/components/esp_wifi/include/esp_now.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 \ - ../../components/esp_event/include/esp_event_base.h \ - ../../components/esp_event/include/esp_event_legacy.h \ + $(IDF_PATH)/components/esp_event/include/esp_event.h \ + $(IDF_PATH)/components/esp_event/include/esp_event_base.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 \ - ../../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_defs.h \ + $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_bt_main.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 \ - ../../components/bt/host/bluedroid/api/include/api/esp_gatts_api.h \ - ../../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_gatt_defs.h \ + $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_gatts_api.h \ + $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_gattc_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 \ - ../../components/bt/host/bluedroid/api/include/api/esp_avrc_api.h \ - ../../components/bt/host/bluedroid/api/include/api/esp_spp_api.h \ - ../../components/bt/host/bluedroid/api/include/api/esp_hf_defs.h \ - ../../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_a2dp_api.h \ + $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_avrc_api.h \ + $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_spp_api.h \ + $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_hf_defs.h \ + $(IDF_PATH)/components/bt/host/bluedroid/api/include/api/esp_hf_client_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 \ - ../../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 \ - ../../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 \ - ../../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 \ - ../../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 \ - ../../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 \ - ../../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/core/include/esp_ble_mesh_common_api.h \ + $(IDF_PATH)/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_low_power_api.h \ + $(IDF_PATH)/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_provisioning_api.h \ + $(IDF_PATH)/components/bt/esp_ble_mesh/api/core/include/esp_ble_mesh_proxy_api.h \ + $(IDF_PATH)/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_generic_model_api.h \ + $(IDF_PATH)/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_lighting_model_api.h \ + $(IDF_PATH)/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_time_scene_model_api.h \ + $(IDF_PATH)/components/bt/esp_ble_mesh/api/esp_ble_mesh_defs.h \ ## ## Ethernet - API Reference ## - ../../components/esp_eth/include/esp_eth.h \ - ../../components/esp_eth/include/esp_eth_com.h \ - ../../components/esp_eth/include/esp_eth_mac.h \ - ../../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.h \ + $(IDF_PATH)/components/esp_eth/include/esp_eth_com.h \ + $(IDF_PATH)/components/esp_eth/include/esp_eth_mac.h \ + $(IDF_PATH)/components/esp_eth/include/esp_eth_phy.h \ + $(IDF_PATH)/components/esp_eth/include/esp_eth_netif_glue.h \ ## ## Peripherals - API Reference ## - ../../components/driver/include/driver/adc.h \ - ../../components/driver/include/driver/can.h \ - ../../components/soc/include/hal/can_types.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/soc/include/hal/mcpwm_types.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/esp32s2/include/temp_sensor.h \ - ../../components/driver/include/driver/timer.h \ - ../../components/driver/include/driver/touch_pad.h \ - ../../components/driver/include/driver/uart.h \ - ../../components/esp_adc_cal/include/esp_adc_cal.h \ - ../../components/soc/include/hal/rmt_types.h \ - ../../components/soc/include/hal/spi_types.h \ - ../../components/soc/include/hal/pcnt_types.h \ - ../../components/soc/include/hal/i2s_types.h \ - ../../components/soc/include/hal/rtc_io_types.h \ - ../../components/soc/include/hal/sigmadelta_types.h \ - ../../components/soc/include/hal/timer_types.h \ - ../../components/soc/include/hal/ledc_types.h \ - ../../components/soc/include/hal/i2c_types.h \ - ../../components/soc/include/hal/dac_types.h \ - ../../components/soc/include/hal/adc_types.h \ - ../../components/soc/include/hal/gpio_types.h \ - ../../components/soc/include/hal/uart_types.h \ - ../../components/soc/include/hal/touch_sensor_types.h \ - ../../components/soc/esp32/include/soc/adc_channel.h \ - ../../components/soc/esp32/include/soc/dac_channel.h \ - ../../components/soc/esp32/include/soc/touch_sensor_channel.h \ - ../../components/soc/esp32/include/soc/uart_channel.h \ - ../../components/soc/esp32/include/soc/rtc_io_channel.h \ + $(IDF_PATH)/components/driver/include/driver/adc.h \ + $(IDF_PATH)/components/driver/include/driver/can.h \ + $(IDF_PATH)/components/soc/include/hal/can_types.h \ + $(IDF_PATH)/components/driver/include/driver/dac.h \ + $(IDF_PATH)/components/driver/include/driver/gpio.h \ + $(IDF_PATH)/components/driver/include/driver/rtc_io.h \ + $(IDF_PATH)/components/driver/include/driver/i2c.h \ + $(IDF_PATH)/components/driver/include/driver/i2s.h \ + $(IDF_PATH)/components/driver/include/driver/ledc.h \ + $(IDF_PATH)/components/driver/include/driver/mcpwm.h \ + $(IDF_PATH)/components/soc/include/hal/mcpwm_types.h \ + $(IDF_PATH)/components/driver/include/driver/pcnt.h \ + $(IDF_PATH)/components/driver/include/driver/rmt.h \ + $(IDF_PATH)/components/driver/include/driver/sigmadelta.h \ + $(IDF_PATH)/components/driver/include/driver/spi_common.h \ + $(IDF_PATH)/components/driver/include/driver/spi_master.h \ + $(IDF_PATH)/components/driver/include/driver/spi_slave.h \ + $(IDF_PATH)/components/driver/esp32s2/include/temp_sensor.h \ + $(IDF_PATH)/components/driver/include/driver/timer.h \ + $(IDF_PATH)/components/driver/include/driver/touch_pad.h \ + $(IDF_PATH)/components/driver/include/driver/uart.h \ + $(IDF_PATH)/components/esp_adc_cal/include/esp_adc_cal.h \ + $(IDF_PATH)/components/soc/include/hal/rmt_types.h \ + $(IDF_PATH)/components/soc/include/hal/spi_types.h \ + $(IDF_PATH)/components/soc/include/hal/pcnt_types.h \ + $(IDF_PATH)/components/soc/include/hal/i2s_types.h \ + $(IDF_PATH)/components/soc/include/hal/rtc_io_types.h \ + $(IDF_PATH)/components/soc/include/hal/sigmadelta_types.h \ + $(IDF_PATH)/components/soc/include/hal/timer_types.h \ + $(IDF_PATH)/components/soc/include/hal/ledc_types.h \ + $(IDF_PATH)/components/soc/include/hal/i2c_types.h \ + $(IDF_PATH)/components/soc/include/hal/dac_types.h \ + $(IDF_PATH)/components/soc/include/hal/adc_types.h \ + $(IDF_PATH)/components/soc/include/hal/gpio_types.h \ + $(IDF_PATH)/components/soc/include/hal/uart_types.h \ + $(IDF_PATH)/components/soc/include/hal/touch_sensor_types.h \ + $(IDF_PATH)/components/soc/esp32/include/soc/adc_channel.h \ + $(IDF_PATH)/components/soc/esp32/include/soc/dac_channel.h \ + $(IDF_PATH)/components/soc/esp32/include/soc/touch_sensor_channel.h \ + $(IDF_PATH)/components/soc/esp32/include/soc/uart_channel.h \ + $(IDF_PATH)/components/soc/esp32/include/soc/rtc_io_channel.h \ ## esp_netif - API Reference - ../../components/esp_netif/include/esp_netif.h \ - ../../components/esp_netif/include/esp_netif_net_stack.h \ + $(IDF_PATH)/components/esp_netif/include/esp_netif.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 \ - ../../components/esp_http_client/include/esp_http_client.h \ - ../../components/esp_websocket_client/include/esp_websocket_client.h \ + $(IDF_PATH)/components/mdns/include/mdns.h \ + $(IDF_PATH)/components/esp_http_client/include/esp_http_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 \ - ../../components/esp_https_server/include/esp_https_server.h \ + $(IDF_PATH)/components/esp_http_server/include/esp_http_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 \ - ../../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.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 \ - ../../components/protocomm/include/security/protocomm_security.h \ - ../../components/protocomm/include/security/protocomm_security0.h \ - ../../components/protocomm/include/security/protocomm_security1.h \ - ../../components/protocomm/include/transports/protocomm_ble.h \ - ../../components/protocomm/include/transports/protocomm_console.h \ - ../../components/protocomm/include/transports/protocomm_httpd.h \ + $(IDF_PATH)/components/protocomm/include/common/protocomm.h \ + $(IDF_PATH)/components/protocomm/include/security/protocomm_security.h \ + $(IDF_PATH)/components/protocomm/include/security/protocomm_security0.h \ + $(IDF_PATH)/components/protocomm/include/security/protocomm_security1.h \ + $(IDF_PATH)/components/protocomm/include/transports/protocomm_ble.h \ + $(IDF_PATH)/components/protocomm/include/transports/protocomm_console.h \ + $(IDF_PATH)/components/protocomm/include/transports/protocomm_httpd.h \ ## WiFi Provisioning - ../../components/wifi_provisioning/include/wifi_provisioning/manager.h \ - ../../components/wifi_provisioning/include/wifi_provisioning/scheme_ble.h \ - ../../components/wifi_provisioning/include/wifi_provisioning/scheme_softap.h \ - ../../components/wifi_provisioning/include/wifi_provisioning/scheme_console.h \ - ../../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/manager.h \ + $(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/scheme_ble.h \ + $(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/scheme_softap.h \ + $(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/scheme_console.h \ + $(IDF_PATH)/components/wifi_provisioning/include/wifi_provisioning/wifi_config.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 \ - ../../components/spi_flash/include/esp_flash.h \ - ../../components/spi_flash/include/esp_partition.h \ - ../../components/bootloader_support/include/esp_flash_encrypt.h \ - ../../components/soc/include/hal/spi_flash_types.h \ + $(IDF_PATH)/components/spi_flash/include/esp_flash_spi_init.h \ + $(IDF_PATH)/components/spi_flash/include/esp_flash.h \ + $(IDF_PATH)/components/spi_flash/include/esp_partition.h \ + $(IDF_PATH)/components/bootloader_support/include/esp_flash_encrypt.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 \ - ../../components/driver/include/driver/sdmmc_host.h \ - ../../components/driver/include/driver/sdmmc_types.h \ - ../../components/driver/include/driver/sdspi_host.h \ + $(IDF_PATH)/components/sdmmc/include/sdmmc_cmd.h \ + $(IDF_PATH)/components/driver/include/driver/sdmmc_host.h \ + $(IDF_PATH)/components/driver/include/driver/sdmmc_types.h \ + $(IDF_PATH)/components/driver/include/driver/sdspi_host.h \ ## SDIO slave - ../../components/driver/include/driver/sdio_slave.h \ - ../../components/soc/include/hal/sdio_slave_types.h \ + $(IDF_PATH)/components/driver/include/driver/sdio_slave.h \ + $(IDF_PATH)/components/soc/include/hal/sdio_slave_types.h \ ## Non-Volatile Storage - ../../components/nvs_flash/include/nvs.h \ - ../../components/nvs_flash/include/nvs_flash.h \ + $(IDF_PATH)/components/nvs_flash/include/nvs.h \ + $(IDF_PATH)/components/nvs_flash/include/nvs_flash.h \ ## Virtual Filesystem - ../../components/vfs/include/esp_vfs.h \ - ../../components/vfs/include/esp_vfs_dev.h \ - ../../components/vfs/include/esp_vfs_semihost.h \ + $(IDF_PATH)/components/vfs/include/esp_vfs.h \ + $(IDF_PATH)/components/vfs/include/esp_vfs_dev.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 \ - ../../components/fatfs/diskio/diskio_impl.h \ - ../../components/fatfs/diskio/diskio_sdmmc.h \ - ../../components/fatfs/diskio/diskio_wl.h \ - ../../components/fatfs/diskio/diskio_rawflash.h \ + $(IDF_PATH)/components/fatfs/vfs/esp_vfs_fat.h \ + $(IDF_PATH)/components/fatfs/diskio/diskio_impl.h \ + $(IDF_PATH)/components/fatfs/diskio/diskio_sdmmc.h \ + $(IDF_PATH)/components/fatfs/diskio/diskio_wl.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 \ - ../../components/heap/include/esp_heap_trace.h \ - ../../components/heap/include/esp_heap_caps_init.h \ - ../../components/heap/include/multi_heap.h \ + $(IDF_PATH)/components/heap/include/esp_heap_caps.h \ + $(IDF_PATH)/components/heap/include/esp_heap_trace.h \ + $(IDF_PATH)/components/heap/include/esp_heap_caps_init.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 \ - ../../components/esp_common/include/esp_task_wdt.h \ + $(IDF_PATH)/components/esp_common/include/esp_int_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 \ - ../../components/ulp/include/ulp_common.h \ + $(IDF_PATH)/components/ulp/include/esp32/ulp.h \ + $(IDF_PATH)/components/ulp/include/ulp_common.h \ ## ## Application Level Tracing - API Reference ## - ../../components/app_trace/include/esp_app_trace.h \ - ../../components/app_trace/include/esp_sysview_trace.h \ + $(IDF_PATH)/components/app_trace/include/esp_app_trace.h \ + $(IDF_PATH)/components/app_trace/include/esp_sysview_trace.h \ ### Power management - ../../components/esp_common/include/esp_pm.h \ - ../../components/esp32/include/esp32/pm.h \ + $(IDF_PATH)/components/esp_common/include/esp_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 \ - ../../components/esp_event/include/esp_event_base.h \ + $(IDF_PATH)/components/esp_event/include/esp_event.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 \ - ../../components/freertos/include/freertos/queue.h \ - ../../components/freertos/include/freertos/semphr.h \ - ../../components/freertos/include/freertos/timers.h \ - ../../components/freertos/include/freertos/event_groups.h \ + $(IDF_PATH)/components/freertos/include/freertos/task.h \ + $(IDF_PATH)/components/freertos/include/freertos/queue.h \ + $(IDF_PATH)/components/freertos/include/freertos/semphr.h \ + $(IDF_PATH)/components/freertos/include/freertos/timers.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 \ - ../../components/freemodbus/common/include/esp_modbus_slave.h \ - ../../components/freemodbus/common/include/esp_modbus_master.h \ + $(IDF_PATH)/components/freemodbus/common/include/esp_modbus_common.h \ + $(IDF_PATH)/components/freemodbus/common/include/esp_modbus_slave.h \ + $(IDF_PATH)/components/freemodbus/common/include/esp_modbus_master.h \ ### Performance Monitor component header file - ../../components/perfmon/include/xtensa_perfmon_access.h \ - ../../components/perfmon/include/xtensa_perfmon_apis.h \ - ../../components/perfmon/include/xtensa_perfmon_masks.h + $(IDF_PATH)/components/perfmon/include/xtensa_perfmon_access.h \ + $(IDF_PATH)/components/perfmon/include/xtensa_perfmon_apis.h \ + $(IDF_PATH)/components/perfmon/include/xtensa_perfmon_masks.h ## Get warnings for functions that have no documentation for their parameters or return value diff --git a/docs/build_docs.py b/docs/build_docs.py new file mode 100755 index 0000000000..47381ee967 --- /dev/null +++ b/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() diff --git a/docs/conf_common.py b/docs/conf_common.py index 9851d17447..b8f811e13d 100644 --- a/docs/conf_common.py +++ b/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. -idf_target = 'esp32s2' +docs_root = os.path.join(idf_path, "docs") 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) - call_with_python('../gen-version-specific-includes.py {} {}'.format(app.config.language, version_tmpdir)) - copy_if_modified(version_tmpdir, '{}/inc'.format(builddir)) + version_tmpdir = '{}/version_inc'.format(build_dir) + call_with_python('{}/gen-version-specific-includes.py {} {}'.format(docs_root, app.config.language, version_tmpdir)) + 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) -call_with_python('../gen-toolchain-links.py ../../tools/toolchain_versions.mk {} {}'.format(base_url, toolchain_tmpdir)) -copy_if_modified(toolchain_tmpdir, '{}/inc'.format(builddir)) +toolchain_tmpdir = '{}/toolchain_inc'.format(build_dir) +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(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) diff --git a/docs/docs_common.mk b/docs/docs_common.mk deleted file mode 100644 index e1298bd661..0000000000 --- a/docs/docs_common.mk +++ /dev/null @@ -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 \' where 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." diff --git a/docs/doxygen_idf.py b/docs/doxygen_idf.py index 79b2429450..4cb49b6dd3 100644 --- a/docs/doxygen_idf.py +++ b/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) diff --git a/docs/en/api-reference/bluetooth/controller_vhci.rst b/docs/en/api-reference/bluetooth/controller_vhci.rst index abc037b662..2f98339290 100644 --- a/docs/en/api-reference/bluetooth/controller_vhci.rst +++ b/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 diff --git a/docs/en/api-reference/bluetooth/esp-ble-mesh.rst b/docs/en/api-reference/bluetooth/esp-ble-mesh.rst index a10c79fe29..62b5703b30 100644 --- a/docs/en/api-reference/bluetooth/esp-ble-mesh.rst +++ b/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 diff --git a/docs/en/api-reference/bluetooth/esp_a2dp.rst b/docs/en/api-reference/bluetooth/esp_a2dp.rst index 873c9405cc..8dea862fc1 100644 --- a/docs/en/api-reference/bluetooth/esp_a2dp.rst +++ b/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 diff --git a/docs/en/api-reference/bluetooth/esp_avrc.rst b/docs/en/api-reference/bluetooth/esp_avrc.rst index ca4993de16..1c15c7b69c 100644 --- a/docs/en/api-reference/bluetooth/esp_avrc.rst +++ b/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 diff --git a/docs/en/api-reference/bluetooth/esp_blufi.rst b/docs/en/api-reference/bluetooth/esp_blufi.rst index 1f20ae16e8..2eb2b2a6d0 100644 --- a/docs/en/api-reference/bluetooth/esp_blufi.rst +++ b/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 diff --git a/docs/en/api-reference/bluetooth/esp_bt_defs.rst b/docs/en/api-reference/bluetooth/esp_bt_defs.rst index 58b2ad03e0..85e73d0688 100644 --- a/docs/en/api-reference/bluetooth/esp_bt_defs.rst +++ b/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 diff --git a/docs/en/api-reference/bluetooth/esp_bt_device.rst b/docs/en/api-reference/bluetooth/esp_bt_device.rst index 936b5a318f..b234cea14c 100644 --- a/docs/en/api-reference/bluetooth/esp_bt_device.rst +++ b/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 diff --git a/docs/en/api-reference/bluetooth/esp_bt_main.rst b/docs/en/api-reference/bluetooth/esp_bt_main.rst index 06055ffadb..321f9331e2 100644 --- a/docs/en/api-reference/bluetooth/esp_bt_main.rst +++ b/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 diff --git a/docs/en/api-reference/bluetooth/esp_gap_ble.rst b/docs/en/api-reference/bluetooth/esp_gap_ble.rst index b997daff7d..8f95906853 100644 --- a/docs/en/api-reference/bluetooth/esp_gap_ble.rst +++ b/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 diff --git a/docs/en/api-reference/bluetooth/esp_gap_bt.rst b/docs/en/api-reference/bluetooth/esp_gap_bt.rst index 38b005b31f..346f7ec90a 100644 --- a/docs/en/api-reference/bluetooth/esp_gap_bt.rst +++ b/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 diff --git a/docs/en/api-reference/bluetooth/esp_gatt_defs.rst b/docs/en/api-reference/bluetooth/esp_gatt_defs.rst index fd383ab72d..931802126f 100644 --- a/docs/en/api-reference/bluetooth/esp_gatt_defs.rst +++ b/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 diff --git a/docs/en/api-reference/bluetooth/esp_gattc.rst b/docs/en/api-reference/bluetooth/esp_gattc.rst index 90f9782b11..708888d2b5 100644 --- a/docs/en/api-reference/bluetooth/esp_gattc.rst +++ b/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 diff --git a/docs/en/api-reference/bluetooth/esp_gatts.rst b/docs/en/api-reference/bluetooth/esp_gatts.rst index 7915a653d8..1b48fccc89 100644 --- a/docs/en/api-reference/bluetooth/esp_gatts.rst +++ b/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 diff --git a/docs/en/api-reference/bluetooth/esp_hf_client.rst b/docs/en/api-reference/bluetooth/esp_hf_client.rst index 7c8a2d88c9..b79eb743f7 100644 --- a/docs/en/api-reference/bluetooth/esp_hf_client.rst +++ b/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 diff --git a/docs/en/api-reference/bluetooth/esp_hf_defs.rst b/docs/en/api-reference/bluetooth/esp_hf_defs.rst index 615b623862..4633a81f67 100644 --- a/docs/en/api-reference/bluetooth/esp_hf_defs.rst +++ b/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 diff --git a/docs/en/api-reference/bluetooth/esp_spp.rst b/docs/en/api-reference/bluetooth/esp_spp.rst index 2a6a6acc51..ced5340899 100644 --- a/docs/en/api-reference/bluetooth/esp_spp.rst +++ b/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 diff --git a/docs/en/api-reference/bluetooth/nimble/index.rst b/docs/en/api-reference/bluetooth/nimble/index.rst index a8ff60d19f..8600c86049 100644 --- a/docs/en/api-reference/bluetooth/nimble/index.rst +++ b/docs/en/api-reference/bluetooth/nimble/index.rst @@ -41,4 +41,4 @@ This documentation does not cover NimBLE APIs. Refer to `NimBLE tutorial `. -.. include:: /_build/inc/esp_err_defs.inc +.. include-build-file:: inc/esp_err_defs.inc diff --git a/docs/en/api-reference/kconfig.rst b/docs/en/api-reference/kconfig.rst index 2c23c8dd4d..21e6b68f16 100644 --- a/docs/en/api-reference/kconfig.rst +++ b/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 ============== diff --git a/docs/en/api-reference/network/esp_eth.rst b/docs/en/api-reference/network/esp_eth.rst index db9990e359..88cd39168f 100644 --- a/docs/en/api-reference/network/esp_eth.rst +++ b/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 diff --git a/docs/en/api-reference/network/esp_mesh.rst b/docs/en/api-reference/network/esp_mesh.rst index 051841a0da..02efbe0349 100644 --- a/docs/en/api-reference/network/esp_mesh.rst +++ b/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 diff --git a/docs/en/api-reference/network/esp_netif.rst b/docs/en/api-reference/network/esp_netif.rst index 77bb21c9f8..16c00cc9a2 100644 --- a/docs/en/api-reference/network/esp_netif.rst +++ b/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 diff --git a/docs/en/api-reference/network/esp_netif_driver.rst b/docs/en/api-reference/network/esp_netif_driver.rst index 4dd7f1c6a8..000d5eb37d 100644 --- a/docs/en/api-reference/network/esp_netif_driver.rst +++ b/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 diff --git a/docs/en/api-reference/network/esp_now.rst b/docs/en/api-reference/network/esp_now.rst index 172e8789f2..83df9f2cb9 100644 --- a/docs/en/api-reference/network/esp_now.rst +++ b/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 diff --git a/docs/en/api-reference/network/esp_smartconfig.rst b/docs/en/api-reference/network/esp_smartconfig.rst index f21453aa57..7b195c6790 100644 --- a/docs/en/api-reference/network/esp_smartconfig.rst +++ b/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 diff --git a/docs/en/api-reference/network/esp_wifi.rst b/docs/en/api-reference/network/esp_wifi.rst index 0d50703802..17dde21e3b 100644 --- a/docs/en/api-reference/network/esp_wifi.rst +++ b/docs/en/api-reference/network/esp_wifi.rst @@ -30,7 +30,7 @@ In addition, there is a simple `esp-idf-template `. 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 diff --git a/docs/en/api-reference/system/freertos_additions.rst b/docs/en/api-reference/system/freertos_additions.rst index ea38fd7d35..969cc2d874 100644 --- a/docs/en/api-reference/system/freertos_additions.rst +++ b/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 diff --git a/docs/en/api-reference/system/heap_debug.rst b/docs/en/api-reference/system/heap_debug.rst index fe0882e9d4..d00f17e480 100644 --- a/docs/en/api-reference/system/heap_debug.rst +++ b/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 diff --git a/docs/en/api-reference/system/himem.rst b/docs/en/api-reference/system/himem.rst index 1c5dd0129a..00529485d5 100644 --- a/docs/en/api-reference/system/himem.rst +++ b/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 diff --git a/docs/en/api-reference/system/intr_alloc.rst b/docs/en/api-reference/system/intr_alloc.rst index 63cf5516e5..da15992432 100644 --- a/docs/en/api-reference/system/intr_alloc.rst +++ b/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 diff --git a/docs/en/api-reference/system/ipc.rst b/docs/en/api-reference/system/ipc.rst index a409719039..5ced8393e6 100644 --- a/docs/en/api-reference/system/ipc.rst +++ b/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 diff --git a/docs/en/api-reference/system/log.rst b/docs/en/api-reference/system/log.rst index 72609c69a1..475439804e 100644 --- a/docs/en/api-reference/system/log.rst +++ b/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 diff --git a/docs/en/api-reference/system/mem_alloc.rst b/docs/en/api-reference/system/mem_alloc.rst index d2e5222f40..65ab940435 100644 --- a/docs/en/api-reference/system/mem_alloc.rst +++ b/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