diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 992887eff..19e727c70 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -608,6 +608,7 @@ build_docs: - cd docs - pip install -r requirements.txt - build-docs -t esp32 esp32s3 esp32c2 esp32c3 esp32c6 esp32h2 esp32p4 -l en + - build-docs -t esp32 -l en linkcheck .deploy_docs_template: stage: docs diff --git a/docs/conf_common.py b/docs/conf_common.py index 14dc5e49a..7dd9d2409 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -1,4 +1,5 @@ from esp_docs.conf_docs import * # noqa: F403,F401 +import subprocess languages = ['en'] idf_targets = ['esp32', 'esp32s3', 'esp32c2', 'esp32c3', 'esp32c6', 'esp32h2', 'esp32p4'] @@ -12,6 +13,39 @@ extensions += ['sphinx_copybutton', # link roles config github_repo = 'espressif/esp-matter' +# Get current commit hash +try: + current_commit = subprocess.check_output(['git', 'rev-parse', '--short','HEAD']).decode('utf-8').strip() +except: + current_commit = 'main' # Fallback if git command fails + +# do not check for anchors +linkcheck_anchors = False +# Add linkcheck configurations +linkcheck_ignore = [ + # Private repositories + 'https://github.com/CHIP-Specifications/.*', + + # Internal documentation links + './developing.html#.*', + './production.html#.*', + + # Ignore self-referential GitHub links with commit hashes + f'https://github.com/{github_repo}/blob/{current_commit}/.*', # Current commit +] + +# Add timeout and HTTP status codes to ignore +linkcheck_timeout = 30 +linkcheck_retries = 3 +linkcheck_ignore_codes = [ + 403, # Forbidden + 429, # Too many requests + 500, # Server errors + 502, # Bad Gateway + 503, # Service unavailable + 504, # Gateway timeout +] + # context used by sphinx_idf_theme html_context['github_user'] = 'espressif' html_context['github_repo'] = 'esp-matter' diff --git a/docs/en/app_guide.rst b/docs/en/app_guide.rst index d479f262f..cc51be547 100644 --- a/docs/en/app_guide.rst +++ b/docs/en/app_guide.rst @@ -262,7 +262,7 @@ ModeWaterHeater, ModeRefrigerator, ModeLaundryWasher and ModeMicrowaveOven. .. _`Energy Evse Mode`: https://github.com/espressif/connectedhomeip/blob/ea679d2dc674f576f4d391d1d71af1489010e580/examples/energy-management-app/energy-management-common/energy-evse/include/energy-evse-modes.h .. _`Microwave Oven Mode`: https://github.com/espressif/connectedhomeip/blob/ea679d2dc674f576f4d391d1d71af1489010e580/examples/all-clusters-app/all-clusters-common/include/microwave-oven-mode.h .. _`Device Energy Management Mode`: https://github.com/espressif/connectedhomeip/blob/ea679d2dc674f576f4d391d1d71af1489010e580/examples/energy-management-app/energy-management-common/device-energy-management/include/device-energy-management-modes.h -.. _`Water Heater Mode`: https://github.com/espressif/connectedhomeip/blob/ea679d2dc674f576f4d391d1d71af1489010e580/examples/energy-management-app/energy-management-common/water-heater/include/water-heater-mode.h +.. _`Water Heater Mode`: https://github.com/espressif/connectedhomeip/blob/ea679d2dc674f576f4d391d1d71af1489010e580/examples/all-clusters-app/all-clusters-common/include/water-heater-mode.h .. _`Energy Evse`: https://github.com/espressif/connectedhomeip/blob/ea679d2dc674f576f4d391d1d71af1489010e580/src/app/clusters/energy-evse-server/energy-evse-server.h .. _`Energy Evse Delegate`: https://github.com/espressif/connectedhomeip/blob/ea679d2dc674f576f4d391d1d71af1489010e580/examples/energy-management-app/energy-management-common/energy-evse/include/EnergyEvseDelegateImpl.h .. _`Operational State`: https://github.com/espressif/connectedhomeip/blob/ea679d2dc674f576f4d391d1d71af1489010e580/src/app/clusters/operational-state-server/operational-state-server.h @@ -299,7 +299,7 @@ ModeWaterHeater, ModeRefrigerator, ModeLaundryWasher and ModeMicrowaveOven. .. _`Mode Select`: https://github.com/espressif/connectedhomeip/blob/ea679d2dc674f576f4d391d1d71af1489010e580/src/app/clusters/mode-select-server/supported-modes-manager.h .. _`Mode Select Delegate`: https://github.com/espressif/connectedhomeip/blob/ea679d2dc674f576f4d391d1d71af1489010e580/examples/all-clusters-app/all-clusters-common/include/static-supported-modes-manager.h .. _`Water Heater Management`: https://github.com/espressif/connectedhomeip/blob/ea679d2dc674f576f4d391d1d71af1489010e580/src/app/clusters/water-heater-management-server/water-heater-management-server.h -.. _`Water Heater Management Delegate`: https://github.com/espressif/connectedhomeip/blob/ea679d2dc674f576f4d391d1d71af1489010e580/examples/energy-management-app/energy-management-common/water-heater/include/WhmDelegate.h +.. _`Water Heater Management Delegate`: https://github.com/espressif/connectedhomeip/blob/ea679d2dc674f576f4d391d1d71af1489010e580/examples/all-clusters-app/all-clusters-common/include/WhmDelegate.h .. _`Energy Preference`: https://github.com/espressif/connectedhomeip/blob/ea679d2dc674f576f4d391d1d71af1489010e580/src/app/clusters/energy-preference-server/energy-preference-server.h .. _`Energy Preference Delegate`: https://github.com/espressif/connectedhomeip/blob/ea679d2dc674f576f4d391d1d71af1489010e580/examples/all-clusters-app/all-clusters-common/src/energy-preference-delegate.cpp .. _`Commissioner Control`: https://github.com/espressif/connectedhomeip/blob/ea679d2dc674f576f4d391d1d71af1489010e580/src/app/clusters/commissioner-control-server/commissioner-control-server.h diff --git a/docs/en/developing.rst b/docs/en/developing.rst index aefff1dc0..6a19dccf4 100644 --- a/docs/en/developing.rst +++ b/docs/en/developing.rst @@ -30,8 +30,8 @@ Development on Windows is supported using Windows Subsystem for Linux (WSL). Ple - Install Ubuntu 20.04 or 22.04 from the `Windows App Store `__. - Start Ubuntu (search into start menu) and run command ``uname -a``, it should report a kernel version of ``5.10.60.1`` or later. If not please upgrade the WSL2. To upgrade the kernel, run ``wsl --upgrade`` from Windows Power Shell. -- Windows does not support exposing COM ports to WSL distros. Install usbipd-win on `Windows `__ - and `WSL `__ (usbipd-win `WSL Support `__). +- Windows does not support exposing COM ports to WSL distros. Install `usbipd-win`_ + and `WSL`_ (`usbipd-win WSL Support`_). - Here onwards process for setting esp-matter and building examples is same as other hosts. - Please clone the repositories from inside the WSL environment and not inside a mounted directory. @@ -496,7 +496,7 @@ Use the cluster commands to control the attributes. chip-tool when used in interactive mode uses CASE resumption as against establishing CASE for cluster control commands. This results into shorter execution times, thereby improving the overall experience. -For more details on chip-tool usage, check https://github.com/espressif/connectedhomeip/tree/v1.0.0.2/examples/chip-tool +For more details about the commands, please check `chip-tool usage guide`_ 2.4 Device console ------------------ @@ -1097,7 +1097,7 @@ We need to generate the new CD because it SHALL match the VID, PID in DAC and th ninja -C build Generate the Test CD, please make sure to change the ``-V`` (vendor_id) and ``-p`` (product-id) options based on the ones that are being used. -For more info about the arguments, please check `here `__. +For more info about the arguments, please check `chip-cert's gen-cd command`_ in the connectedhomeip repository. :: @@ -1199,7 +1199,7 @@ Run the following command from host to commission the device. - Enable the ``CONFIG_ENABLE_OTA_REQUESTOR`` option to enable Matter OTA Requestor functionality. -Please follow the `guide `__ +Please follow the `OTA guide`_ in the connectedhomeip repository for generating a Matter OTA image and performing OTA. 2.8.1 Encrypted Matter OTA @@ -1224,7 +1224,7 @@ Please follow the steps below to enable and use encrypted application images for } -- Please refer to the `guide `__ +- Please refer to the `encrypted OTA guide`_ in the connectedhomeip repository for instructions on how to generate a private key, encrypted OTA image, and Matter OTA image. .. note:: @@ -1695,14 +1695,21 @@ To enable these functions, the cluster should be added to the appropriate entry If the example uses ESP-Matter APIs to define its data model, the custom data model should be created and added to the data model using the esp-matter APIs, following the instructions in `Adding custom data model fields <./developing.html#adding-custom-data-model-fields>`__ .. _`step by step installation guide`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-macos-setup.html -.. _`Prerequisites for ESP-IDF`: https://docs.espressif.com/projects/esp-idf/en/v5.0.1/esp32/get-started/index.html#step-1-install-prerequisites -.. _`Prerequisites for Matter`: https://github.com/espressif/connectedhomeip/blob/v1.1-branch/docs/guides/BUILDING.md#prerequisites +.. _`Prerequisites for ESP-IDF`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html#installation +.. _`Prerequisites for Matter`: https://github.com/project-chip/connectedhomeip/tree/master/docs/guides/BUILDING.md#prerequisites .. _`esp-matter-mfg-tool`: https://github.com/espressif/esp-matter-tools/tree/main/mfg_tool .. _`zcl configuration file`: https://github.com/project-chip/connectedhomeip/blob/master/src/app/zap-templates/zcl/zcl.json .. _`zcl test configuration file`: https://github.com/project-chip/connectedhomeip/blob/master/src/app/zap-templates/zcl/zcl-with-test-extensions.json -.. _`zap configuration data`: +.. _`zap configuration data`: https://github.com/project-chip/connectedhomeip/blob/master/src/app/common/templates/config-data.yaml .. _`ESP-Rainmaker iOS App`: https://apps.apple.com/app/esp-rainmaker/id1497491540 .. _`ESP-Rainmaker Android App`: https://play.google.com/store/apps/details?id=com.espressif.rainmaker .. _`connectedhomeip`: https://github.com/project-chip/connectedhomeip .. _`CHIP Tool User Guide`: https://github.com/project-chip/connectedhomeip/blob/master/docs/development_controllers/chip-tool/chip_tool_guide.md .. _`profile installation instructions`: https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/darwin.md#profile-installation +.. _`OTA guide`: https://github.com/project-chip/connectedhomeip/blob/master/docs/platforms/esp32/ota.md +.. _`encrypted OTA guide`: https://github.com/project-chip/connectedhomeip/blob/master/docs/platforms/esp32/ota.md#encrypted-ota +.. _`chip-cert's gen-cd command`: https://github.com/espressif/connectedhomeip/tree/v1.0.0.2/src/tools/chip-cert#gen-cd +.. _usbipd-win: https://github.com/dorssel/usbipd-win +.. _WSL: https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/additionalfeatures/wsl.html#usbipd-win-in-wsl +.. _`usbipd-win WSL Support`: https://github.com/dorssel/usbipd-win/wiki/WSL-support +.. _`chip-tool usage guide`: https://github.com/project-chip/connectedhomeip/blob/master/docs/development_controllers/chip-tool/chip_tool_guide.md \ No newline at end of file diff --git a/docs/en/faq.rst b/docs/en/faq.rst index 9c146436f..4b57329d0 100644 --- a/docs/en/faq.rst +++ b/docs/en/faq.rst @@ -414,12 +414,11 @@ Please check `#1123`_ for relevant discussion on Github issue. .. _light_wifi_prov: https://github.com/espressif/esp-matter/tree/main/examples/light_wifi_prov#4-external-platform .. _getting the repository: https://docs.espressif.com/projects/esp-matter/en/latest/esp32/developing.html#getting-the-repository .. _requirements.txt: https://github.com/espressif/esp-matter/blob/main/requirements.txt -.. _implementation which frees the BLE memory: https://github.com/espressif/esp-matter/blob/c52fa686d1a3be275b0a5c872ee5f1a3c8f2420d/components/esp_matter/esp_matter_core.cpp#L859-L891 .. _generate_setup_payload.py: https://github.com/project-chip/connectedhomeip/tree/master/src/setup_payload/python .. _CHIP QR Code: https://project-chip.github.io/connectedhomeip/qrcode.html -.. _CONFIG_APP_PROJECT_VER_FROM_CONFIG: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/kconfig.html#config-app-project-ver-from-config -.. _UART console baud rate: https://docs.espressif.com/projects/esp-idf/en/latest/esp32c2/api-reference/kconfig.html#config-esp-console-uart-baudrate -.. _Main XTAL frequency: https://docs.espressif.com/projects/esp-idf/en/latest/esp32c2/api-reference/kconfig.html#main-xtal-config +.. _CONFIG_APP_PROJECT_VER_FROM_CONFIG: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/kconfig-reference.html#config-app-project-ver-from-config +.. _UART console baud rate: https://docs.espressif.com/projects/esp-idf/en/latest/esp32c2/api-reference/kconfig-reference.html#config-esp-console-uart-baudrate +.. _Main XTAL frequency: https://docs.espressif.com/projects/esp-idf/en/latest/esp32c2/api-reference/kconfig-reference.html#main-xtal-config .. _Github issue: https://github.com/espressif/esp-matter/issues/new?template=issue-template.md .. _`#1123`: https://github.com/espressif/esp-matter/issues/1123 diff --git a/docs/en/insights.rst b/docs/en/insights.rst index c6ac1a99b..ac628d8d4 100644 --- a/docs/en/insights.rst +++ b/docs/en/insights.rst @@ -1,9 +1,9 @@ Enabling ESP-Insights in ESP-Matter =================================== -- To learn more about esp-insights and get started, please refer [project README.md] (https://github.com/espressif/esp-insights/blob/main/README.md). +- To learn more about esp-insights and get started, please refer `project README.md`_. - Before building the app, enable the option `ESP_INSIGHTS_ENABLED` through menuconfig. -- Follow the steps present [here](https://github.com/espressif/esp-insights/blob/main/examples/README.md#set-up-esp-insights-account) to set up an `insights_account`, and create an auth key. +- Follow the steps present `set up esp-insights account`_ , and create an auth key. - Create a file named `insights_auth_key.txt` in the project directory of the example. - Download the auth key and copy Auth Key to the example. @@ -11,7 +11,8 @@ Enabling ESP-Insights in ESP-Matter cp /path/to/auth/key.txt path/to/esp-matter/examples/generic_switch/insights_auth_key.txt -- Refer the esp-matter [generic switch example](https://github.com/espressif/esp-matter/blob/main/examples/generic_switch/main/app_main.cpp) to enable the traces and metrics reported by the esp32 tracing backend in the chip SDK on the insights dashboard and about how to use the auth key for enabling insights. +- Refer the esp-matter :project_file:`Generic Switch example ` to enable the traces and metrics reported by the esp32 tracing backend in the chip SDK on the insights dashboard and about how to use the auth key for enabling insights. - Enable the option `ENABLE_ESP_INSIGHTS_SYSTEM_STATS` to get a report of the system metrics in the chip SDK on the insights dashboard. - +.. _project README.md: https://github.com/espressif/esp-insights/blob/main/README.md +.. _set up esp-insights account: https://github.com/espressif/esp-insights/blob/main/examples/README.md#set-up-esp-insights-account \ No newline at end of file