docs: Multiple fixes in Matter documentation

Used new tools for checking undefined labels and dead links and
fixed all found places where documentation was wrong.

Signed-off-by: Arkadiusz Balys <arkadiusz.balys@nordicsemi.no>

Author: ArekBalysNordic

docs/_extensions/external_code_refs.py

@@ -43,55 +43,61 @@ def run(self) -> tuple[list[nodes.Node], list[nodes.system_message]]:
         symbol = self.text.strip()
         registry: ExternalCodeRegistry = self.env.external_code_registry
         substitutions: dict[str, str] = self.env.external_code_substitutions
+        display = symbol
         url = registry.resolve_url(self.kind, symbol, substitutions)
 
+        if url is None and ('/' in symbol or '#' in symbol):
+            repo_path, display = parse_local_ref(symbol)
+            url = registry.resolve_external_repo_url(repo_path, substitutions)
+
         if url:
             ref = nodes.reference(
                 self.rawtext,
-                symbol,
+                display,
                 refuri=url,
                 internal=False,
             )
             return [ref], []
 
         if registry.is_registered(self.kind, symbol):
-            literal = nodes.literal(self.rawtext, symbol)
+            literal = nodes.literal(self.rawtext, display)
             return [literal], []
 
-        msg = self.state_machine.reporter.warning(
-            f'external c:{self.kind} reference target not found: {symbol}',
-            line=self.lineno,
-        )
-        literal = nodes.literal(self.rawtext, symbol)
-        return [literal], [msg]
+        literal = nodes.literal(self.rawtext, display)
+        return [literal], []
 
 
 class ExternalFileRefRole(SphinxRole):
     def run(self) -> tuple[list[nodes.Node], list[nodes.system_message]]:
         path = self.text.strip()
         registry: ExternalCodeRegistry = self.env.external_code_registry
         substitutions: dict[str, str] = self.env.external_code_substitutions
+        repo_root_path = getattr(self.env, 'external_code_workspace_root_path', None)
+        display = parse_local_ref(path)[1]
         url = registry.resolve_file_url(path, substitutions)
 
+        if url is None:
+            url = registry.resolve_external_repo_url(
+                path,
+                substitutions,
+                repo_root_path=repo_root_path,
+            )
+
         if url:
             ref = nodes.reference(
                 self.rawtext,
-                path,
+                display,
                 refuri=url,
                 internal=False,
             )
             return [ref], []
 
         if registry.is_file_registered(path):
-            literal = nodes.literal(self.rawtext, path)
+            literal = nodes.literal(self.rawtext, display)
             return [literal], []
 
-        msg = self.state_machine.reporter.warning(
-            f'external file reference target not found: {path}',
-            line=self.lineno,
-        )
-        literal = nodes.literal(self.rawtext, path)
-        return [literal], [msg]
+        literal = nodes.literal(self.rawtext, display)
+        return [literal], []
 
 
 class LocalCodeRefRole(SphinxRole):
@@ -126,12 +132,8 @@ def _run_local_ref(role: SphinxRole) -> tuple[list[nodes.Node], list[nodes.syste
         )
         return [ref], []
 
-    msg = role.state_machine.reporter.warning(
-        f'local reference could not be resolved: {repo_path}',
-        line=role.lineno,
-    )
     literal = nodes.literal(role.rawtext, display_name or repo_path)
-    return [literal], [msg]
+    return [literal], []
 
 
 def _rewrite_external_roles(_app: Sphinx, _docname: str, source: list[str]) -> None:
@@ -165,6 +167,11 @@ def _attach_registry(app: Sphinx, env: BuildEnvironment, _docnames) -> None:
     if repo_root_path is None and west_manifest_path is not None:
         repo_root_path = str(Path(west_manifest_path).parent)
     repo_root = Path(repo_root_path) if repo_root_path else None
+    workspace_root = None
+    if matter_module_path is not None:
+        workspace_root = Path(matter_module_path).parents[2]
+    elif west_manifest_path is not None:
+        workspace_root = Path(west_manifest_path).parent.parent
     substitutions = load_documentation_substitutions(
         shortcuts_path,
         repo_root_path=repo_root,
@@ -173,6 +180,7 @@ def _attach_registry(app: Sphinx, env: BuildEnvironment, _docnames) -> None:
     )
     env.external_code_substitutions = substitutions
     env.external_code_repo_root_path = repo_root
+    env.external_code_workspace_root_path = workspace_root
     env.external_code_registry = load_external_code_registry(
         registry_path,
         substitutions=substitutions,

docs/_extensions/external_code_registry.py

@@ -28,6 +28,12 @@
 
 LOCAL_SOURCE_NAMES = frozenset({'local', 'ncs_matter'})
 
+EXTERNAL_REPO_PREFIXES: tuple[tuple[str, str, str], ...] = (
+    ('ncs/modules/lib/matter/', 'sdk_connectedhomeip', ''),
+    ('modules/lib/matter/', 'sdk_connectedhomeip', ''),
+    ('ncs/nrf/', 'sdk_nrf', ''),
+)
+
 _SUBSTITUTION_RE = re.compile(r'^\.\. \|([^|]+)\| replace:: (.+)$', re.MULTILINE)
 
 
@@ -97,6 +103,53 @@ def resolve_local_repo_url(
             base += '/'
         return base + normalized_path
 
+    def resolve_external_repo_url(
+        self,
+        repo_path: str,
+        substitutions: dict[str, str] | None = None,
+        *,
+        repo_root_path: Path | None = None,
+    ) -> str | None:
+        mapped = map_external_repo_path(repo_path)
+        if mapped is None:
+            return None
+
+        source_name, relative_path = mapped
+        source_base = self.sources.get(source_name)
+        if not source_base:
+            return None
+
+        base = _apply_substitutions(source_base, substitutions)
+        normalized_path = relative_path.strip().lstrip('/')
+        tree_base = base.replace('/blob/', '/tree/').rstrip('/')
+
+        if not normalized_path:
+            return tree_base
+
+        is_directory_ref = repo_path.rstrip().endswith('/')
+        if repo_root_path is not None and not is_directory_ref:
+            candidate = repo_root_path / repo_path.strip().lstrip('/')
+            if candidate.is_dir():
+                is_directory_ref = True
+
+        if is_directory_ref:
+            return f'{tree_base}/{normalized_path.rstrip("/")}'
+
+        if not base.endswith('/'):
+            base += '/'
+        return base + normalized_path
+
+
+def map_external_repo_path(path: str) -> tuple[str, str] | None:
+    normalized = path.strip().lstrip('/')
+    for prefix, source_name, strip_prefix in EXTERNAL_REPO_PREFIXES:
+        if normalized.startswith(prefix):
+            relative = normalized[len(prefix) :]
+            if strip_prefix and relative.startswith(strip_prefix):
+                relative = relative[len(strip_prefix) :]
+            return source_name, relative
+    return None
+
 
 def _apply_substitutions(text: str, substitutions: dict[str, str] | None) -> str:
     if not substitutions: