Merge branch 'docs/show_include_path' into 'master'

docs: show include path and require component as part of API header

Closes IDF-3134, DOC-1032, and DOC-3629

See merge request espressif/esp-idf!25092
This commit is contained in:
Marius Vikhammer 2023-10-11 09:36:14 +08:00
commit d27dd4d9cb
17 changed files with 179 additions and 88 deletions

View File

@ -33,6 +33,10 @@ mainmenu "Espressif IoT Development Framework Configuration"
bool
default y if "$(IDF_CI_BUILD)" = "y" || "$(IDF_CI_BUILD)" = 1
config IDF_DOC_BUILD
bool
default y if "$(IDF_DOC_BUILD)" = "y" || "$(IDF_DOC_BUILD)" = 1
config IDF_TOOLCHAIN
# This option records the IDF target when sdkconfig is generated the first time.
# It is not updated if environment variable $IDF_TOOLCHAIN changes later, and

View File

@ -1,3 +1,64 @@
# API headers that are used in the docs are also compiled
# even if CONFIG_BT_ENABLED=n as long as CONFIG_IDF_DOC_BUILD=y
if(CONFIG_IDF_TARGET_ESP32)
set(target_specific_include_dirs include/esp32/include)
elseif(CONFIG_IDF_TARGET_ESP32C3)
set(target_specific_include_dirs include/esp32c3/include)
elseif(CONFIG_IDF_TARGET_ESP32S3)
set(target_specific_include_dirs include/esp32c3/include)
elseif(CONFIG_IDF_TARGET_ESP32C2)
set(target_specific_include_dirs include/esp32c2/include)
elseif(CONFIG_IDF_TARGET_ESP32C6)
set(target_specific_include_dirs include/esp32c6/include)
elseif(CONFIG_IDF_TARGET_ESP32H2)
set(target_specific_include_dirs include/esp32h2/include)
endif()
set(common_include_dirs
common/api/include/api
common/btc/profile/esp/blufi/include
common/btc/profile/esp/include
)
set(ble_mesh_include_dirs
"esp_ble_mesh/common/include"
"esp_ble_mesh/common/tinycrypt/include"
"esp_ble_mesh/core"
"esp_ble_mesh/core/include"
"esp_ble_mesh/core/storage"
"esp_ble_mesh/btc/include"
"esp_ble_mesh/models/common/include"
"esp_ble_mesh/models/client/include"
"esp_ble_mesh/models/server/include"
"esp_ble_mesh/api/core/include"
"esp_ble_mesh/api/models/include"
"esp_ble_mesh/api"
"esp_ble_mesh/v1.1/api/core/include"
"esp_ble_mesh/v1.1/api/models/include"
"esp_ble_mesh/v1.1/btc/include"
"esp_ble_mesh/v1.1/include"
)
set(bluedroid_include_dirs host/bluedroid/api/include/api)
set(nimble_hci_include_dirs host/nimble/esp-hci/include)
if(CONFIG_IDF_DOC_BUILD)
list(APPEND include_dirs
${target_specific_include_dirs}
${common_include_dirs}
${ble_mesh_include_dirs}
${bluedroid_include_dirs}
${nimble_hci_include_dirs})
endif()
if(CONFIG_BT_ENABLED)
set(srcs "")
@ -7,29 +68,24 @@ if(CONFIG_BT_ENABLED)
list(APPEND srcs "controller/esp32/bt.c"
"controller/esp32/hli_api.c"
"controller/esp32/hli_vectors.S")
list(APPEND include_dirs include/esp32/include)
elseif(CONFIG_IDF_TARGET_ESP32C3)
list(APPEND srcs "controller/esp32c3/bt.c")
list(APPEND include_dirs include/esp32c3/include)
elseif(CONFIG_IDF_TARGET_ESP32S3)
list(APPEND srcs "controller/esp32c3/bt.c")
list(APPEND include_dirs include/esp32c3/include)
elseif(CONFIG_IDF_TARGET_ESP32C2)
list(APPEND srcs "controller/esp32c2/bt.c")
list(APPEND include_dirs include/esp32c2/include)
elseif(CONFIG_IDF_TARGET_ESP32C6)
list(APPEND srcs "controller/esp32c6/bt.c")
list(APPEND include_dirs include/esp32c6/include)
elseif(CONFIG_IDF_TARGET_ESP32H2)
list(APPEND srcs "controller/esp32h2/bt.c")
list(APPEND include_dirs include/esp32h2/include)
endif()
list(APPEND include_dirs ${target_specific_include_dirs})
# Common
list(APPEND include_dirs common/osi/include)
@ -39,12 +95,7 @@ if(CONFIG_BT_ENABLED)
common/include
porting/mem/
)
list(APPEND include_dirs
common/api/include/api
common/btc/profile/esp/blufi/include
common/btc/profile/esp/include
)
list(APPEND include_dirs ${common_include_dirs})
list(APPEND srcs "common/btc/core/btc_alarm.c"
"common/api/esp_blufi_api.c"
@ -111,7 +162,7 @@ if(CONFIG_BT_ENABLED)
host/bluedroid/common/include
host/bluedroid/config/include)
list(APPEND include_dirs host/bluedroid/api/include/api)
list(APPEND include_dirs ${bluedroid_include_dirs})
list(APPEND srcs "host/bluedroid/api/esp_a2dp_api.c"
"host/bluedroid/api/esp_avrc_api.c"
@ -378,23 +429,7 @@ if(CONFIG_BT_ENABLED)
endif()
if(CONFIG_BLE_MESH)
list(APPEND include_dirs
"esp_ble_mesh/common/include"
"esp_ble_mesh/common/tinycrypt/include"
"esp_ble_mesh/core"
"esp_ble_mesh/core/include"
"esp_ble_mesh/core/storage"
"esp_ble_mesh/btc/include"
"esp_ble_mesh/models/common/include"
"esp_ble_mesh/models/client/include"
"esp_ble_mesh/models/server/include"
"esp_ble_mesh/api/core/include"
"esp_ble_mesh/api/models/include"
"esp_ble_mesh/api"
"esp_ble_mesh/v1.1/api/core/include"
"esp_ble_mesh/v1.1/api/models/include"
"esp_ble_mesh/v1.1/btc/include"
"esp_ble_mesh/v1.1/include")
list(APPEND include_dirs ${ble_mesh_include_dirs})
list(APPEND srcs "esp_ble_mesh/api/core/esp_ble_mesh_ble_api.c"
"esp_ble_mesh/api/core/esp_ble_mesh_common_api.c"
@ -665,9 +700,7 @@ if(CONFIG_BT_ENABLED)
list(APPEND srcs
"host/nimble/esp-hci/src/esp_nimble_hci.c"
)
list(APPEND include_dirs
host/nimble/esp-hci/include
)
list(APPEND include_dirs ${nimble_hci_include_dirs})
endif()
list(APPEND srcs

View File

@ -19,6 +19,6 @@ idf_component_register(SRCS "commands.c"
"split_argv.c"
"linenoise/linenoise.c"
${argtable_srcs}
INCLUDE_DIRS "."
INCLUDE_DIRS ${CMAKE_CURRENT_SOURCE_DIR}
REQUIRES vfs
PRIV_REQUIRES driver)

View File

@ -15,7 +15,7 @@ if(NOT ${IDF_TARGET} STREQUAL "linux")
endif()
idf_component_register(SRCS "${srcs}"
INCLUDE_DIRS . esp-tls-crypto
INCLUDE_DIRS ${CMAKE_CURRENT_SOURCE_DIR} esp-tls-crypto
PRIV_INCLUDE_DIRS "private_include"
# mbedtls is public requirements becasue esp_tls.h
# includes mbedtls header files.

View File

@ -1,4 +1,4 @@
if(CONFIG_ESP_HTTPS_SERVER_ENABLE)
if(CONFIG_ESP_HTTPS_SERVER_ENABLE OR CONFIG_IDF_DOC_BUILD)
set(src "src/https_server.c")
set(inc "include")
endif()

View File

@ -1,9 +1,11 @@
if(CONFIG_OPENTHREAD_ENABLED)
idf_build_get_property(idf_target IDF_TARGET)
if(CONFIG_OPENTHREAD_ENABLED OR CONFIG_IDF_DOC_BUILD)
set(public_include_dirs
"include"
"openthread/include")
endif()
if(CONFIG_OPENTHREAD_ENABLED)
idf_build_get_property(idf_target IDF_TARGET)
set(private_include_dirs
"openthread/examples/platforms"

View File

@ -3,52 +3,56 @@ idf_build_get_property(target IDF_TARGET)
set(srcs "")
set(includes "")
if(CONFIG_ULP_COPROC_TYPE_FSM OR CONFIG_SOC_RISCV_COPROC_SUPPORTED)
if(CONFIG_ULP_COPROC_ENABLED OR (CONFIG_IDF_DOC_BUILD AND CONFIG_SOC_ULP_SUPPORTED))
list(APPEND includes
ulp_common/include
ulp_common/include/${target})
endif()
if(CONFIG_ULP_COPROC_TYPE_FSM OR (CONFIG_IDF_DOC_BUILD AND CONFIG_SOC_ULP_FSM_SUPPORTED))
list(APPEND includes
ulp_fsm/include
ulp_fsm/include/${target})
endif()
if(CONFIG_ULP_COPROC_TYPE_RISCV OR CONFIG_IDF_DOC_BUILD)
list(APPEND includes
ulp_riscv/include
ulp_riscv/shared/include)
endif()
if(CONFIG_ULP_COPROC_TYPE_LP_CORE OR CONFIG_IDF_DOC_BUILD)
list(APPEND includes
lp_core/include
lp_core/shared/include)
endif()
if(CONFIG_ULP_COPROC_TYPE_FSM OR CONFIG_ULP_COPROC_TYPE_RISCV)
list(APPEND srcs
"ulp_common/ulp_common.c"
"ulp_common/ulp_adc.c")
list(APPEND includes
ulp_common/include
ulp_common/include/${target})
if(CONFIG_ULP_COPROC_TYPE_FSM)
list(APPEND srcs
"ulp_fsm/ulp.c"
"ulp_fsm/ulp_macro.c")
list(APPEND includes
ulp_fsm/include
ulp_fsm/include/${target})
elseif(CONFIG_ULP_COPROC_TYPE_RISCV)
list(APPEND srcs
"ulp_riscv/ulp_riscv.c"
"ulp_riscv/ulp_riscv_lock.c"
"ulp_riscv/ulp_riscv_i2c.c")
list(APPEND includes
ulp_riscv/include
ulp_riscv/shared/include)
endif()
endif()
if(CONFIG_ULP_COPROC_TYPE_LP_CORE)
list(APPEND includes
ulp_common/include
ulp_common/include/${target})
list(APPEND srcs
"lp_core/lp_core.c"
"lp_core/shared/ulp_lp_core_memory_shared.c"
"lp_core/shared/ulp_lp_core_lp_timer_shared.c"
"lp_core/lp_core_i2c.c"
"lp_core/lp_core_uart.c")
list(APPEND includes
"lp_core/include"
"lp_core/shared/include")
endif()
idf_component_register(SRCS ${srcs}

View File

@ -0,0 +1,10 @@
# Header files that will be ignored when generating extra header information
# For API reference (include path/REQUIRE component)
# ULP header files for the ULP app do not have an IDF header path/component require
components/ulp/lp_core/lp_core/include/ulp_lp_core_gpio.h
components/ulp/lp_core/lp_core/include/ulp_lp_core_i2c.h
components/ulp/lp_core/lp_core/include/ulp_lp_core_utils.h
# ESSL headers do not belong to any IDF component, in a user project it will come from a managed component
components/driver/test_apps/components/esp_serial_slave_link/include/esp_serial_slave_link/essl_sdio.h
components/driver/test_apps/components/esp_serial_slave_link/include/esp_serial_slave_link/essl_spi.h
components/driver/test_apps/components/esp_serial_slave_link/include/esp_serial_slave_link/essl.h

View File

@ -13,6 +13,7 @@ from __future__ import print_function, unicode_literals
import os.path
import re
from pathlib import Path
from esp_docs.conf_docs import * # noqa: F403,F401
@ -294,6 +295,8 @@ html_redirect_pages = [tuple(line.split(' ')) for line in lines]
html_static_path = ['../_static']
idf_build_system = {'doxygen_component_info': True, 'component_info_ignore_file': Path(os.environ['IDF_PATH']) / 'docs' / 'component_info_ignore_file.txt'}
# Callback function for user setup that needs be done after `config-init`-event
# config.idf_target is not available at the initial config stage

View File

@ -180,8 +180,6 @@ INPUT = \
$(PROJECT_PATH)/components/esp_netif/include/esp_vfs_l2tap.h \
$(PROJECT_PATH)/components/esp_netif/include/esp_netif_sntp.h \
$(PROJECT_PATH)/components/esp_partition/include/esp_partition.h \
$(PROJECT_PATH)/components/esp_phy/include/esp_phy_init.h \
$(PROJECT_PATH)/components/esp_phy/include/esp_phy_cert_test.h \
$(PROJECT_PATH)/components/esp_pm/include/esp_pm.h \
$(PROJECT_PATH)/components/esp_ringbuf/include/freertos/ringbuf.h \
$(PROJECT_PATH)/components/esp_rom/include/esp_rom_sys.h \
@ -262,9 +260,6 @@ INPUT = \
$(PROJECT_PATH)/components/openthread/include/esp_openthread_netif_glue.h \
$(PROJECT_PATH)/components/openthread/include/esp_openthread_types.h \
$(PROJECT_PATH)/components/openthread/include/esp_openthread.h \
$(PROJECT_PATH)/components/perfmon/include/xtensa_perfmon_access.h \
$(PROJECT_PATH)/components/perfmon/include/xtensa_perfmon_apis.h \
$(PROJECT_PATH)/components/perfmon/include/xtensa_perfmon_masks.h \
$(PROJECT_PATH)/components/protocomm/include/common/protocomm.h \
$(PROJECT_PATH)/components/protocomm/include/security/protocomm_security.h \
$(PROJECT_PATH)/components/protocomm/include/security/protocomm_security0.h \
@ -284,25 +279,6 @@ INPUT = \
$(PROJECT_PATH)/components/spi_flash/include/spi_flash_mmap.h \
$(PROJECT_PATH)/components/spi_flash/include/esp_spi_flash_counters.h \
$(PROJECT_PATH)/components/spiffs/include/esp_spiffs.h \
$(PROJECT_PATH)/components/touch_element/include/touch_element/touch_button.h \
$(PROJECT_PATH)/components/touch_element/include/touch_element/touch_element.h \
$(PROJECT_PATH)/components/touch_element/include/touch_element/touch_matrix.h \
$(PROJECT_PATH)/components/touch_element/include/touch_element/touch_slider.h \
$(PROJECT_PATH)/components/ulp/ulp_common/include/ulp_common.h \
$(PROJECT_PATH)/components/ulp/ulp_fsm/include/ulp_fsm_common.h \
$(PROJECT_PATH)/components/ulp/ulp_riscv/include/ulp_riscv_lock.h \
$(PROJECT_PATH)/components/ulp/ulp_riscv/include/ulp_riscv.h \
$(PROJECT_PATH)/components/ulp/ulp_riscv/include/ulp_riscv_i2c.h \
$(PROJECT_PATH)/components/ulp/ulp_riscv/shared/include/ulp_riscv_lock_shared.h \
$(PROJECT_PATH)/components/ulp/lp_core/include/lp_core_i2c.h \
$(PROJECT_PATH)/components/ulp/lp_core/include/ulp_lp_core.h \
$(PROJECT_PATH)/components/ulp/lp_core/lp_core/include/ulp_lp_core_gpio.h \
$(PROJECT_PATH)/components/ulp/lp_core/lp_core/include/ulp_lp_core_i2c.h \
$(PROJECT_PATH)/components/ulp/lp_core/lp_core/include/ulp_lp_core_utils.h \
$(PROJECT_PATH)/components/usb/include/usb/usb_helpers.h \
$(PROJECT_PATH)/components/usb/include/usb/usb_host.h \
$(PROJECT_PATH)/components/usb/include/usb/usb_types_ch9.h \
$(PROJECT_PATH)/components/usb/include/usb/usb_types_stack.h \
$(PROJECT_PATH)/components/vfs/include/esp_vfs_dev.h \
$(PROJECT_PATH)/components/vfs/include/esp_vfs_eventfd.h \
$(PROJECT_PATH)/components/vfs/include/esp_vfs_semihost.h \

View File

@ -7,3 +7,10 @@ INPUT += \
$(PROJECT_PATH)/components/ulp/ulp_common/include/$(IDF_TARGET)/ulp_common_defs.h \
$(PROJECT_PATH)/components/ulp/ulp_fsm/include/$(IDF_TARGET)/ulp.h \
$(PROJECT_PATH)/components/bt/include/$(IDF_TARGET)/include/esp_bt.h \
$(PROJECT_PATH)/components/perfmon/include/xtensa_perfmon_access.h \
$(PROJECT_PATH)/components/perfmon/include/xtensa_perfmon_apis.h \
$(PROJECT_PATH)/components/perfmon/include/xtensa_perfmon_masks.h \
$(PROJECT_PATH)/components/esp_phy/include/esp_phy_init.h \
$(PROJECT_PATH)/components/esp_phy/include/esp_phy_cert_test.h \
$(PROJECT_PATH)/components/ulp/ulp_fsm/include/ulp_fsm_common.h \
$(PROJECT_PATH)/components/ulp/ulp_common/include/ulp_common.h \

View File

@ -1,2 +1,4 @@
INPUT += \
$(PROJECT_PATH)/components/bt/include/$(IDF_TARGET)/include/esp_bt.h \
$(PROJECT_PATH)/components/bt/include/esp32c2/include/esp_bt.h \
$(PROJECT_PATH)/components/esp_phy/include/esp_phy_init.h \
$(PROJECT_PATH)/components/esp_phy/include/esp_phy_cert_test.h \

View File

@ -1,2 +1,4 @@
INPUT += \
$(PROJECT_PATH)/components/bt/include/$(IDF_TARGET)/include/esp_bt.h \
$(PROJECT_PATH)/components/bt/include/esp32c3/include/esp_bt.h \
$(PROJECT_PATH)/components/esp_phy/include/esp_phy_init.h \
$(PROJECT_PATH)/components/esp_phy/include/esp_phy_cert_test.h \

View File

@ -1,2 +1,10 @@
INPUT += \
$(PROJECT_PATH)/components/bt/include/$(IDF_TARGET)/include/esp_bt.h \
$(PROJECT_PATH)/components/ulp/lp_core/include/lp_core_i2c.h \
$(PROJECT_PATH)/components/ulp/lp_core/include/ulp_lp_core.h \
$(PROJECT_PATH)/components/ulp/lp_core/lp_core/include/ulp_lp_core_gpio.h \
$(PROJECT_PATH)/components/ulp/lp_core/lp_core/include/ulp_lp_core_i2c.h \
$(PROJECT_PATH)/components/ulp/lp_core/lp_core/include/ulp_lp_core_utils.h \
$(PROJECT_PATH)/components/bt/include/esp32c6/include/esp_bt.h \
$(PROJECT_PATH)/components/esp_phy/include/esp_phy_init.h \
$(PROJECT_PATH)/components/esp_phy/include/esp_phy_cert_test.h \
$(PROJECT_PATH)/components/ulp/ulp_common/include/ulp_common.h \

View File

@ -1,2 +1,4 @@
INPUT += \
$(PROJECT_PATH)/components/bt/include/$(IDF_TARGET)/include/esp_bt.h \
$(PROJECT_PATH)/components/bt/include/esp32h2/include/esp_bt.h \
$(PROJECT_PATH)/components/esp_phy/include/esp_phy_init.h \
$(PROJECT_PATH)/components/esp_phy/include/esp_phy_cert_test.h \

View File

@ -5,3 +5,22 @@ INPUT += \
$(PROJECT_PATH)/components/soc/$(IDF_TARGET)/include/soc/touch_sensor_channel.h \
$(PROJECT_PATH)/components/ulp/ulp_common/include/$(IDF_TARGET)/ulp_common_defs.h \
$(PROJECT_PATH)/components/ulp/ulp_fsm/include/$(IDF_TARGET)/ulp.h \
$(PROJECT_PATH)/components/touch_element/include/touch_element/touch_button.h \
$(PROJECT_PATH)/components/touch_element/include/touch_element/touch_element.h \
$(PROJECT_PATH)/components/touch_element/include/touch_element/touch_matrix.h \
$(PROJECT_PATH)/components/touch_element/include/touch_element/touch_slider.h \
$(PROJECT_PATH)/components/usb/include/usb/usb_helpers.h \
$(PROJECT_PATH)/components/usb/include/usb/usb_host.h \
$(PROJECT_PATH)/components/usb/include/usb/usb_types_ch9.h \
$(PROJECT_PATH)/components/usb/include/usb/usb_types_stack.h \
$(PROJECT_PATH)/components/perfmon/include/xtensa_perfmon_access.h \
$(PROJECT_PATH)/components/perfmon/include/xtensa_perfmon_apis.h \
$(PROJECT_PATH)/components/perfmon/include/xtensa_perfmon_masks.h \
$(PROJECT_PATH)/components/esp_phy/include/esp_phy_init.h \
$(PROJECT_PATH)/components/esp_phy/include/esp_phy_cert_test.h \
$(PROJECT_PATH)/components/ulp/ulp_riscv/include/ulp_riscv_lock.h \
$(PROJECT_PATH)/components/ulp/ulp_riscv/include/ulp_riscv.h \
$(PROJECT_PATH)/components/ulp/ulp_riscv/include/ulp_riscv_i2c.h \
$(PROJECT_PATH)/components/ulp/ulp_riscv/shared/include/ulp_riscv_lock_shared.h \
$(PROJECT_PATH)/components/ulp/ulp_fsm/include/ulp_fsm_common.h \
$(PROJECT_PATH)/components/ulp/ulp_common/include/ulp_common.h \

View File

@ -3,4 +3,23 @@ INPUT += \
$(PROJECT_PATH)/components/soc/$(IDF_TARGET)/include/soc/touch_sensor_channel.h \
$(PROJECT_PATH)/components/ulp/ulp_common/include/$(IDF_TARGET)/ulp_common_defs.h \
$(PROJECT_PATH)/components/ulp/ulp_fsm/include/$(IDF_TARGET)/ulp.h \
$(PROJECT_PATH)/components/touch_element/include/touch_element/touch_button.h \
$(PROJECT_PATH)/components/touch_element/include/touch_element/touch_element.h \
$(PROJECT_PATH)/components/touch_element/include/touch_element/touch_matrix.h \
$(PROJECT_PATH)/components/touch_element/include/touch_element/touch_slider.h \
$(PROJECT_PATH)/components/usb/include/usb/usb_helpers.h \
$(PROJECT_PATH)/components/usb/include/usb/usb_host.h \
$(PROJECT_PATH)/components/usb/include/usb/usb_types_ch9.h \
$(PROJECT_PATH)/components/usb/include/usb/usb_types_stack.h \
$(PROJECT_PATH)/components/bt/include/esp32c3/include/esp_bt.h \
$(PROJECT_PATH)/components/perfmon/include/xtensa_perfmon_access.h \
$(PROJECT_PATH)/components/perfmon/include/xtensa_perfmon_apis.h \
$(PROJECT_PATH)/components/perfmon/include/xtensa_perfmon_masks.h \
$(PROJECT_PATH)/components/esp_phy/include/esp_phy_init.h \
$(PROJECT_PATH)/components/esp_phy/include/esp_phy_cert_test.h \
$(PROJECT_PATH)/components/ulp/ulp_riscv/include/ulp_riscv_lock.h \
$(PROJECT_PATH)/components/ulp/ulp_riscv/include/ulp_riscv.h \
$(PROJECT_PATH)/components/ulp/ulp_riscv/include/ulp_riscv_i2c.h \
$(PROJECT_PATH)/components/ulp/ulp_riscv/shared/include/ulp_riscv_lock_shared.h \
$(PROJECT_PATH)/components/ulp/ulp_fsm/include/ulp_fsm_common.h \
$(PROJECT_PATH)/components/ulp/ulp_common/include/ulp_common.h \