ci: Divide checkers to docs and samples

- One workflow will check documentation and the other one samples.

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

Author: ArekBalysNordic

.github/workflows/doc-validation.yml

@@ -0,0 +1,64 @@
+name: Matter Documentation Validation
+
+on:
+  pull_request:
+    branches:
+      - main
+      - 'v*-branch'
+
+    paths:
+      - 'docs/**'
+      - 'samples/**/*.rst'
+      - 'scripts/matter_sample_checker/**'
+      - '.github/workflows/doc-validation.yml'
+      - 'west.yml'
+
+permissions:
+  contents: read
+
+env:
+  WEST_PATH_CACHE: ${{ github.workspace }}/west-path-cache
+
+jobs:
+  matter-doc-validation:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout the code
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          path: ncs-matter
+
+      - name: Set up Python
+        uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38 # v5
+        with:
+          python-version: 3.12
+          cache: pip
+          cache-dependency-path: |
+            ncs-matter/scripts/requirements.txt
+            ncs-matter/docs/requirements-doc.txt
+
+      - name: Install packages
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y wget python3-pip git
+          pip install -r ncs-matter/scripts/requirements.txt
+          pip install -r ncs-matter/docs/requirements-doc.txt
+
+      - name: Restore west module path cache
+        uses: actions/cache@d4323d4df104b026a6aa633fdb11d772146be0bf # v4
+        with:
+          path: west-path-cache
+          key: west-path-cache-${{ hashFiles('ncs-matter/west.yml') }}
+          restore-keys: |
+            west-path-cache-
+
+      - name: Prepare west workspace
+        run: |
+          rm -rf .west
+          west init -l ncs-matter --mf west.yml
+          west update -n -o=--depth=1 --path-cache "${WEST_PATH_CACHE}"
+
+      - name: Validate Matter documentation
+        run: |
+          python ncs-matter/scripts/matter_sample_checker/matter_doc_checker.py \
+            --base ncs-matter

.github/workflows/sample-validation.yml

@@ -56,7 +56,7 @@ jobs:
           west init -l ncs-matter --mf west.yml
           west update -n -o=--depth=1 --path-cache "${WEST_PATH_CACHE}"
 
-      - name: validate Matter samples and documentation
+      - name: Validate Matter samples
         run: |
           python ncs-matter/scripts/matter_sample_checker/matter_sample_checker.py \
             --samples-zap-yaml ncs-matter/scripts/zap_samples.yml \

scripts/matter_sample_checker/checks/docs/check_doc_links.py

@@ -50,8 +50,18 @@
     "[ref.envvar]",
 )
 LINKCHECK_BROKEN_RE = re.compile(
-    r"^(?P<line>\d+) \[(?P<status>broken|redirected|ignored).*?\] "
-    r"(?P<uri>\S+?)(?: to .*?)?$"
+    r"^(?:"
+    r"(?P<source>.+?):(?P<line>\d+):\s*"
+    r"|(?P<output_line>\d+)\s+"
+    r")\[(?P<status>[^\]]+)\]\s+"
+    r"(?P<uri>\S+)"
+)
+LINKCHECK_OUTPUT_LINE_RE = re.compile(
+    r"^(?:"
+    r"(?P<source>.+?):(?P<line>\d+):\s*"
+    r"|(?P<output_line>\d+)\s+"
+    r")\[(?P<status>[^\]]+)\]\s+"
+    r"(?P<uri>\S+)(?P<detail>.*)$"
 )
 SPHINX_PERCENT_RE = re.compile(r"\[\s*(\d+)%\]\s*(.*)$")
 SPHINX_PHASE_RE = re.compile(
@@ -114,6 +124,119 @@ def sphinx_line(self, line: str) -> None:
     def reset_percent(self) -> None:
         self._last_percent = -1
 
+    def replay_log(self, heading: str, lines: Sequence[str]) -> None:
+        if self.quiet or not lines:
+            return
+        self.info(heading)
+        for line in lines:
+            self.info(f"  {line}")
+
+
+def _read_text(path: Path) -> str:
+    if not path.is_file():
+        return ""
+    return path.read_text(encoding="utf-8", errors="replace")
+
+
+def _sphinx_log_lines(log_text: str) -> list[str]:
+    """Extract warning/error lines from a Sphinx build or warning log."""
+    lines: list[str] = []
+    seen: set[str] = set()
+
+    for raw_line in log_text.splitlines():
+        stripped = raw_line.strip()
+        if not stripped or stripped.startswith("$ ") or stripped.startswith("exit_code:"):
+            continue
+        if SPHINX_PERCENT_RE.search(stripped) or SPHINX_PHASE_RE.search(stripped):
+            continue
+
+        normalized = stripped
+        match = SPHINX_ISSUE_RE.match(raw_line)
+        if match:
+            normalized = (
+                f"{match.group('file')}:{match.group('line')}: "
+                f"{match.group('level')}: {match.group('message')}"
+            )
+        elif stripped.startswith("WARNING: ") or stripped.startswith("ERROR: "):
+            normalized = stripped
+        elif " WARNING:" not in raw_line and " ERROR:" not in raw_line:
+            continue
+
+        if normalized not in seen:
+            seen.add(normalized)
+            lines.append(normalized)
+
+    return lines
+
+
+def _linkcheck_output_lines(output_text: str) -> tuple[list[str], list[str]]:
+    """Split linkcheck output.txt lines into info (broken) and debug (other) buckets."""
+    info_lines: list[str] = []
+    debug_lines: list[str] = []
+    seen: set[str] = set()
+
+    for raw_line in output_text.splitlines():
+        stripped = raw_line.strip()
+        if not stripped or stripped in seen:
+            continue
+        seen.add(stripped)
+
+        match = LINKCHECK_OUTPUT_LINE_RE.match(stripped)
+        if match:
+            status = match.group("status")
+            uri = match.group("uri")
+            detail = (match.group("detail") or "").rstrip()
+            source = match.group("source")
+            line_no = match.group("line") or match.group("output_line")
+            location = f"{source}:{line_no}" if source and line_no else f"linkcheck:{line_no or '?'}"
+            suffix = detail if not detail or detail.startswith((" ", "\t")) else f" {detail}"
+            message = f"{location}: [{status}] {uri}{suffix}"
+            if status.startswith("broken"):
+                info_lines.append(message)
+            else:
+                debug_lines.append(message)
+            continue
+
+        if "[broken" in stripped.lower():
+            info_lines.append(stripped)
+        elif "[redirected" in stripped.lower() or "[ignored" in stripped.lower():
+            debug_lines.append(stripped)
+        else:
+            debug_lines.append(stripped)
+
+    return info_lines, debug_lines
+
+
+def _emit_sphinx_build_log(progress: ProgressLog, log_path: Path, *, heading: str) -> None:
+    lines = _sphinx_log_lines(_read_text(log_path))
+    if lines:
+        progress.replay_log(heading, lines)
+    elif not progress.quiet:
+        progress.info(f"{heading}: no warnings or errors recorded")
+
+
+def _emit_linkcheck_logs(
+    progress: ProgressLog,
+    log_path: Path,
+    output_path: Path,
+) -> None:
+    broken_lines, other_lines = _linkcheck_output_lines(_read_text(output_path))
+    warning_lines = _sphinx_log_lines(_read_text(log_path))
+
+    if broken_lines:
+        progress.replay_log("External linkcheck broken URLs:", broken_lines)
+    elif not progress.quiet:
+        progress.info("External linkcheck broken URLs: none")
+
+    if other_lines:
+        progress.info("External linkcheck other results:")
+        for line in other_lines:
+            progress.debug(f"  {line}")
+
+    extra_warnings = [line for line in warning_lines if line not in broken_lines]
+    if extra_warnings:
+        progress.replay_log("Sphinx linkcheck warnings:", extra_warnings)
+
 
 @dataclass(frozen=True)
 class DocLinksPaths:
@@ -317,14 +440,24 @@ def _parse_linkcheck_output(output_path: Path) -> list[LinkIssue]:
 
     issues: list[LinkIssue] = []
     for raw_line in output_path.read_text(encoding="utf-8", errors="replace").splitlines():
-        match = LINKCHECK_BROKEN_RE.match(raw_line)
-        if not match or match.group("status") != "broken":
+        match = LINKCHECK_BROKEN_RE.match(raw_line.strip())
+        if not match or not match.group("status").startswith("broken"):
             continue
+
+        source = match.group("source")
+        line_str = match.group("line") or match.group("output_line")
+        if source and line_str:
+            issue_source = f"{source}:{line_str}"
+            issue_line = int(line_str)
+        else:
+            issue_source = str(output_path)
+            issue_line = int(line_str) if line_str else None
+
         issues.append(
             LinkIssue(
                 check="external-link",
-                source=str(output_path),
-                line=int(match.group("line")),
+                source=issue_source,
+                line=issue_line,
                 message="unreachable URL",
                 target=match.group("uri"),
             )
@@ -429,9 +562,8 @@ def check_cross_references(
             )
         )
 
-    progress.info(
-        f"Cross-reference check finished with {len(issues)} issue(s); log: {log_path}"
-    )
+    progress.info(f"Cross-reference check finished with {len(issues)} issue(s)")
+    _emit_sphinx_build_log(progress, log_path, heading="Cross-reference Sphinx log")
     return issues, str(log_path)
 
 
@@ -469,9 +601,8 @@ def check_external_links(
             )
         )
 
-    progress.info(
-        f"External link check finished with {len(issues)} broken URL(s); log: {log_path}"
-    )
+    progress.info(f"External link check finished with {len(issues)} broken URL(s)")
+    _emit_linkcheck_logs(progress, log_path, output_txt)
     return issues, str(log_path), str(output_txt)
 
 
@@ -617,16 +748,6 @@ def check(self):
             self.warning(f"Optional documentation links check skipped: {exc}")
             return
 
-        if report.intersphinx_docsets:
-            self.debug(f"Intersphinx docsets: {', '.join(report.intersphinx_docsets)}")
-        else:
-            self.debug(
-                "No local NCS docset inventories found; only in-addon :ref: targets validated"
-            )
-
-        for log_name, log_path in report.log_paths.items():
-            self.debug(f"{log_name}: {log_path}")
-
         for link_issue in report.issues:
             self.issue(_format_link_issue(link_issue))
 

scripts/matter_sample_checker/internal/cli_common.py

@@ -0,0 +1,80 @@
+#
+# Copyright (c) 2026 Nordic Semiconductor ASA
+#
+# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+
+"""Shared CLI helpers for matter_sample_checker and matter_doc_checker."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from datetime import datetime
+from pathlib import Path
+
+
+def checker_script_dir() -> Path:
+    return Path(__file__).resolve().parent.parent
+
+
+def default_config_path() -> Path:
+    return checker_script_dir() / "matter_sample_checker_config.yaml"
+
+
+def add_common_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--base",
+        "-b",
+        type=str,
+        help="Base directory for resolving workspace paths. If not specified, uses the "
+        "ncs-matter repository root containing this script.",
+    )
+    parser.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        help="Show verbose output during checks",
+    )
+    parser.add_argument(
+        "--config",
+        "-c",
+        type=str,
+        help="Path to custom configuration YAML file. Default: matter_sample_checker_config.yaml "
+        "in the checker script directory.",
+    )
+
+
+def resolve_workspace_base(base_arg: str | None) -> Path:
+    if base_arg:
+        return Path(base_arg).resolve()
+
+    script_repo_root = checker_script_dir().parent.parent
+    if (script_repo_root / "west.yml").exists() and (script_repo_root / "samples").is_dir():
+        return script_repo_root
+
+    zephyr_base = os.environ.get("ZEPHYR_BASE")
+    if not zephyr_base:
+        print(
+            "Error: --base not specified and ncs-matter repository root could not be inferred.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    nrf_base = Path(zephyr_base).resolve().parent / "ncs-matter"
+    if not nrf_base.is_dir():
+        print(f"Error: Could not infer ncs-matter workspace base: {nrf_base}", file=sys.stderr)
+        sys.exit(1)
+    return nrf_base
+
+
+def resolve_config_path(config_arg: str | None) -> Path:
+    return Path(config_arg) if config_arg else default_config_path()
+
+
+def parse_expected_years(year_arg: list[int] | None) -> list[int]:
+    if year_arg is None:
+        return []
+    if len(year_arg) == 0:
+        return [datetime.now().year]
+    return year_arg