docs: Fix broken links and add CI for link checking

- 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

Author: shubhamdp

.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

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

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

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

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

@@ -1,17 +1,18 @@
 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.
 
    ::
 
       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