espressif/esp-matter
1
0
Fork 0
mirror of https://github.com/espressif/esp-matter.git synced 2026-04-27 19:13:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Fix broken links and add CI for link checking

Browse Source 
- Ran linkcheck on the built docs and fixed broken links
- Added exceptions for private, anchors, and server errors
  that may come up when we run the linkcheck in CI.
- Also ignore self-referential GitHub links with commit hashes
- Fixed links on the insights page
- Converted some links to use the anchored format
- Fixes #1319
This commit is contained in:
Shubham Patil
2025-03-08 18:54:20 +05:30
parent f3724fe898
commit 5cb96e8b3d
6 changed files with 61 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitlab-ci.yml
+1
View File
@@ -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
docs/conf_common.py
+34
View File
@@ -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'
docs/en/app_guide.rst
+2 -2
View File
@@ -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
docs/en/developing.rst
+16 -9
View File
@@ -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 <https://apps.microsoft.com/store/search/Ubuntu>`__.
- 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 <https://github.com/dorssel/usbipd-win>`__
and `WSL <https://github.com/espressif/vscode-esp-idf-extension/blob/master/docs/WSL.md#usbipd>`__ (usbipd-win `WSL Support <https://github.com/dorssel/usbipd-win/wiki/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 <https://github.com/espressif/connectedhomeip/tree/v1.0.0.2/src/tools/chip-cert#gen-cd>`__.
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 <https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/esp32/ota.md>`__
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 <https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/esp32/ota.md#encrypted-ota>`__
- 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`: <https://github.com/project-chip/connectedhomeip/blob/master/src/app/common/templates/config-data.yaml>
.. _`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
docs/en/faq.rst
+3 -4
View File
@@ -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
docs/en/insights.rst
+5 -4
View File
@@ -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 <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.
- 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