From c30851292fdf6e85514afe2f12c1f92c049e4e0c Mon Sep 17 00:00:00 2001 From: "igor.masar" Date: Mon, 2 Mar 2026 23:20:19 +0100 Subject: [PATCH] docs(usb): Update links and example checks Replace the peripherals index USB entries with direct links to ESP-USB so the generated pages are no longer redirect-only stubs. Keep legacy USB URLs working via redirects, including the individual USB host maintainer notes pages. Remove the obsolete placeholder documents and stale CODEOWNERS pattern. Mark the moved USB examples as KNOWN_MISSING in the example documentation checker until it can also read the ESP-USB guide. --- .gitlab/CODEOWNERS | 1 - docs/conf_common.py | 13 +++++-------- docs/docs_not_updated/esp32c61.txt | 2 -- docs/docs_not_updated/esp32h21.txt | 2 -- docs/en/api-reference/peripherals/index.rst | 4 ++-- docs/en/api-reference/peripherals/usb_device.rst | 6 ------ docs/en/api-reference/peripherals/usb_host.rst | 6 ------ docs/page_redirects.txt | 14 +++++++++++--- docs/zh_CN/api-reference/peripherals/index.rst | 4 ++-- .../zh_CN/api-reference/peripherals/usb_device.rst | 6 ------ docs/zh_CN/api-reference/peripherals/usb_host.rst | 6 ------ tools/ci/check_examples_documented.py | 13 +++++++++++++ 12 files changed, 33 insertions(+), 44 deletions(-) delete mode 100644 docs/en/api-reference/peripherals/usb_device.rst delete mode 100644 docs/en/api-reference/peripherals/usb_host.rst delete mode 100644 docs/zh_CN/api-reference/peripherals/usb_device.rst delete mode 100644 docs/zh_CN/api-reference/peripherals/usb_host.rst diff --git a/.gitlab/CODEOWNERS b/.gitlab/CODEOWNERS index eba6b025a3..667d0d9f2d 100644 --- a/.gitlab/CODEOWNERS +++ b/.gitlab/CODEOWNERS @@ -177,7 +177,6 @@ /docs/**/api-reference/bluetooth/ @esp-idf-codeowners/bluetooth /docs/**/api-reference/network/ @esp-idf-codeowners/network @esp-idf-codeowners/wifi /docs/**/api-reference/peripherals/ @esp-idf-codeowners/peripherals -/docs/**/api-reference/peripherals/usb* @esp-idf-codeowners/peripherals @esp-idf-codeowners/peripherals/usb /docs/**/api-reference/protocols/ @esp-idf-codeowners/network @esp-idf-codeowners/app-utilities /docs/**/api-reference/provisioning/ @esp-idf-codeowners/app-utilities/provisioning /docs/**/api-reference/storage/ @esp-idf-codeowners/storage diff --git a/docs/conf_common.py b/docs/conf_common.py index 5c3db11c42..81e26364dd 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -154,11 +154,6 @@ TOUCH_SENSOR_DOCS = ['api-reference/peripherals/cap_touch_sens.rst'] SPIRAM_DOCS = ['api-guides/external-ram.rst'] -USB_DOCS = [ - 'api-reference/peripherals/usb_device.rst', - 'api-reference/peripherals/usb_host.rst', -] - I80_LCD_DOCS = ['api-reference/peripherals/lcd/i80_lcd.rst'] RGB_LCD_DOCS = ['api-reference/peripherals/lcd/rgb_lcd.rst'] DSI_LCD_DOCS = ['api-reference/peripherals/lcd/dsi_lcd.rst'] @@ -351,7 +346,6 @@ conditional_include_dict = { 'SOC_SDMMC_HOST_SUPPORTED': SDMMC_DOCS, 'SOC_SDIO_SLAVE_SUPPORTED': SDIO_SLAVE_DOCS, 'SOC_MCPWM_SUPPORTED': MCPWM_DOCS, - 'SOC_USB_OTG_SUPPORTED': USB_DOCS, 'SOC_USB_SERIAL_JTAG_SUPPORTED': USB_SERIAL_JTAG_DOCS, 'SOC_DEDICATED_GPIO_SUPPORTED': DEDIC_GPIO_DOCS, 'SOC_LCD_I80_SUPPORTED': I80_LCD_DOCS, @@ -501,9 +495,10 @@ QEMU_TARGETS = ['esp32', 'esp32c3', 'esp32s3'] ESP_TEE_TARGETS = ['esp32c6', 'esp32h2', 'esp32c5', 'esp32c61'] -def _resolve_redirect_page_macros(redirect_pages, target): +def _resolve_redirect_page_macros(redirect_pages, target, language): replace_map = { '{IDF_TARGET_PATH_NAME}': target, + '{IDF_DOCS_LANGUAGE}': language, } resolved_redirect_pages = [] @@ -537,7 +532,9 @@ def conf_setup(app, config): # Not for all target pass - config.html_redirect_pages = _resolve_redirect_page_macros(config.html_redirect_pages, config.idf_target) + config.html_redirect_pages = _resolve_redirect_page_macros( + config.html_redirect_pages, config.idf_target, config.language + ) config.html_baseurl = f'https://docs.espressif.com/projects/esp-idf/{config.language}/stable/{config.idf_target}' diff --git a/docs/docs_not_updated/esp32c61.txt b/docs/docs_not_updated/esp32c61.txt index 9d68d04582..65356a1993 100644 --- a/docs/docs_not_updated/esp32c61.txt +++ b/docs/docs_not_updated/esp32c61.txt @@ -22,8 +22,6 @@ api-reference/storage/mass_mfg.rst api-reference/storage/fatfsgen.rst api-reference/storage/index.rst api-reference/storage/nvs_partition_parse.rst -api-reference/peripherals/usb_host.rst -api-reference/peripherals/usb_device.rst api-reference/peripherals/sd_pullup_requirements.rst api-reference/network/esp_eth.rst api-reference/network/esp_netif_driver.rst diff --git a/docs/docs_not_updated/esp32h21.txt b/docs/docs_not_updated/esp32h21.txt index 32ae626f73..884fe94591 100644 --- a/docs/docs_not_updated/esp32h21.txt +++ b/docs/docs_not_updated/esp32h21.txt @@ -105,8 +105,6 @@ api-reference/peripherals/cap_touch_sens.rst api-reference/peripherals/index.rst api-reference/peripherals/sdio_slave.rst api-reference/peripherals/temp_sensor.rst -api-reference/peripherals/usb_device.rst -api-reference/peripherals/usb_host.rst api-reference/peripherals/camera_driver.rst api-reference/peripherals/adc_oneshot.rst api-reference/peripherals/sdspi_share.rst diff --git a/docs/en/api-reference/peripherals/index.rst b/docs/en/api-reference/peripherals/index.rst index d58f00bb6e..bcdb1e0a26 100644 --- a/docs/en/api-reference/peripherals/index.rst +++ b/docs/en/api-reference/peripherals/index.rst @@ -49,7 +49,7 @@ Peripherals API :SOC_TOUCH_SENSOR_SUPPORTED: cap_touch_sens :SOC_TWAI_SUPPORTED: twai uart - :SOC_USB_OTG_SUPPORTED: usb_device - :SOC_USB_OTG_SUPPORTED: usb_host + :SOC_USB_OTG_SUPPORTED: USB Device Stack + :SOC_USB_OTG_SUPPORTED: USB Host Code examples for this API section are provided in the :example:`peripherals` directory of ESP-IDF examples. diff --git a/docs/en/api-reference/peripherals/usb_device.rst b/docs/en/api-reference/peripherals/usb_device.rst deleted file mode 100644 index 422483ec38..0000000000 --- a/docs/en/api-reference/peripherals/usb_device.rst +++ /dev/null @@ -1,6 +0,0 @@ -USB Device Stack -================ - -:link_to_translation:`zh_CN:[中文]` - -USB Device documentation has moved to `ESP-USB `_. diff --git a/docs/en/api-reference/peripherals/usb_host.rst b/docs/en/api-reference/peripherals/usb_host.rst deleted file mode 100644 index bcd6e6d4e5..0000000000 --- a/docs/en/api-reference/peripherals/usb_host.rst +++ /dev/null @@ -1,6 +0,0 @@ -USB Host -======== - -:link_to_translation:`zh_CN:[中文]` - -USB Host documentation has moved to `ESP-USB `_. diff --git a/docs/page_redirects.txt b/docs/page_redirects.txt index 8c043176fa..13b346d93e 100644 --- a/docs/page_redirects.txt +++ b/docs/page_redirects.txt @@ -16,9 +16,17 @@ api-reference/ethernet/esp_eth api-reference/network/esp_eth api-reference/mesh/index api-reference/network/index api-reference/mesh/esp_mesh api-reference/network/esp_mesh api-reference/peripherals/can api-reference/peripherals/twai -api-reference/peripherals/usb api-reference/peripherals/usb_device -api-reference/peripherals/usb_device "https://docs.espressif.com/projects/esp-usb/en/latest/{IDF_TARGET_PATH_NAME}/usb_device.html" -api-reference/peripherals/usb_host "https://docs.espressif.com/projects/esp-usb/en/latest/{IDF_TARGET_PATH_NAME}/usb_host.html" +api-reference/peripherals/usb "https://docs.espressif.com/projects/esp-usb/{IDF_DOCS_LANGUAGE}/latest/{IDF_TARGET_PATH_NAME}/usb_device.html" +api-reference/peripherals/usb_device "https://docs.espressif.com/projects/esp-usb/{IDF_DOCS_LANGUAGE}/latest/{IDF_TARGET_PATH_NAME}/usb_device.html" +api-reference/peripherals/usb_host "https://docs.espressif.com/projects/esp-usb/{IDF_DOCS_LANGUAGE}/latest/{IDF_TARGET_PATH_NAME}/usb_host.html" +api-reference/peripherals/usb_host/usb_host_notes_index "https://docs.espressif.com/projects/esp-usb/en/latest/{IDF_TARGET_PATH_NAME}/usb_host/usb_host_notes_index.html" +api-reference/peripherals/usb_host/usb_host_notes_arch "https://docs.espressif.com/projects/esp-usb/en/latest/{IDF_TARGET_PATH_NAME}/usb_host/usb_host_notes_arch.html" +api-reference/peripherals/usb_host/usb_host_notes_design "https://docs.espressif.com/projects/esp-usb/en/latest/{IDF_TARGET_PATH_NAME}/usb_host/usb_host_notes_design.html" +api-reference/peripherals/usb_host/usb_host_notes_dwc_otg "https://docs.espressif.com/projects/esp-usb/en/latest/{IDF_TARGET_PATH_NAME}/usb_host/usb_host_notes_dwc_otg.html" +api-reference/peripherals/usb_host/usb_host_notes_usbh "https://docs.espressif.com/projects/esp-usb/en/latest/{IDF_TARGET_PATH_NAME}/usb_host/usb_host_notes_usbh.html" +api-reference/peripherals/usb_host/usb_host_notes_enum "https://docs.espressif.com/projects/esp-usb/en/latest/{IDF_TARGET_PATH_NAME}/usb_host/usb_host_notes_enum.html" +api-reference/peripherals/usb_host/usb_host_notes_ext_hub "https://docs.espressif.com/projects/esp-usb/en/latest/{IDF_TARGET_PATH_NAME}/usb_host/usb_host_notes_ext_hub.html" +api-reference/peripherals/usb_host/usb_host_notes_ext_port "https://docs.espressif.com/projects/esp-usb/en/latest/{IDF_TARGET_PATH_NAME}/usb_host/usb_host_notes_ext_port.html" api-reference/wifi/index api-reference/network/index api-reference/wifi/esp_now api-reference/network/esp_now api-reference/wifi/esp_smartconfig api-reference/network/esp_smartconfig diff --git a/docs/zh_CN/api-reference/peripherals/index.rst b/docs/zh_CN/api-reference/peripherals/index.rst index 8b66cc9869..c33ced5c04 100644 --- a/docs/zh_CN/api-reference/peripherals/index.rst +++ b/docs/zh_CN/api-reference/peripherals/index.rst @@ -49,7 +49,7 @@ :SOC_TOUCH_SENSOR_SUPPORTED: cap_touch_sens :SOC_TWAI_SUPPORTED: twai uart - :SOC_USB_OTG_SUPPORTED: usb_device - :SOC_USB_OTG_SUPPORTED: usb_host + :SOC_USB_OTG_SUPPORTED: USB 设备栈 + :SOC_USB_OTG_SUPPORTED: USB 主机 本部分的 API 示例代码存放在 ESP-IDF 示例项目的 :example:`peripherals` 目录下。 diff --git a/docs/zh_CN/api-reference/peripherals/usb_device.rst b/docs/zh_CN/api-reference/peripherals/usb_device.rst deleted file mode 100644 index 36c4d19f34..0000000000 --- a/docs/zh_CN/api-reference/peripherals/usb_device.rst +++ /dev/null @@ -1,6 +0,0 @@ -USB 设备栈 -========== - -:link_to_translation:`en:[English]` - -USB 设备文档已迁移到 `ESP-USB `_。 diff --git a/docs/zh_CN/api-reference/peripherals/usb_host.rst b/docs/zh_CN/api-reference/peripherals/usb_host.rst deleted file mode 100644 index 6c61392806..0000000000 --- a/docs/zh_CN/api-reference/peripherals/usb_host.rst +++ /dev/null @@ -1,6 +0,0 @@ -USB 主机 -======== - -:link_to_translation:`en:[English]` - -USB 主机文档已迁移到 `ESP-USB `_。 diff --git a/tools/ci/check_examples_documented.py b/tools/ci/check_examples_documented.py index 4f2ada41a0..fa40be81c3 100644 --- a/tools/ci/check_examples_documented.py +++ b/tools/ci/check_examples_documented.py @@ -150,8 +150,21 @@ KNOWN_MISSING = { 'peripherals/spi_slave_hd/segment_mode/seg_slave', 'peripherals/twai/twai_network/twai_listen_only', 'peripherals/twai/twai_network/twai_sender', + # TODO: remove once the checker can also account for the ESP-USB programming guide. 'peripherals/usb/device/cherryusb_serial_device', + 'peripherals/usb/device/tusb_composite_msc_serialdevice', + 'peripherals/usb/device/tusb_console', + 'peripherals/usb/device/tusb_hid', + 'peripherals/usb/device/tusb_midi', + 'peripherals/usb/device/tusb_msc', + 'peripherals/usb/device/tusb_ncm', + 'peripherals/usb/device/tusb_serial_device', + 'peripherals/usb/host/cdc', 'peripherals/usb/host/cherryusb_host', + 'peripherals/usb/host/hid', + 'peripherals/usb/host/msc', + 'peripherals/usb/host/usb_host_lib', + 'peripherals/usb/host/uvc', # TODO IDF-15383: add :example: references for protocols examples 'protocols/dns_over_https', 'protocols/http_request',