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

Kconfig

@@ -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

components/bt/CMakeLists.txt

@@ -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

components/console/CMakeLists.txt

@@ -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)

components/esp-tls/CMakeLists.txt

@@ -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.

components/esp_https_server/CMakeLists.txt

@@ -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()

components/openthread/CMakeLists.txt

@@ -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"

components/ulp/CMakeLists.txt

@@ -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}

docs/component_info_ignore_file.txt

@@ -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

docs/conf_common.py

@@ -13,6 +13,7 @@
 
 import os.path
 import re
+from pathlib import Path
 
 from esp_docs.conf_docs import *  # noqa: F403,F401
 
@@ -294,6 +295,8 @@
 
 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

docs/doxygen/Doxyfile

@@ -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 \

docs/doxygen/Doxyfile_esp32

@@ -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 \

docs/doxygen/Doxyfile_esp32c2

@@ -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 \

docs/doxygen/Doxyfile_esp32c3

@@ -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 \

docs/doxygen/Doxyfile_esp32c6

@@ -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 \

docs/doxygen/Doxyfile_esp32h2

@@ -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 \