doc: extensions: check dead zephyr_file/zephyr_raw links

Add a check to ensure that all zephyr_file/zephyr_raw links are pointing
to valid paths in the current zephyr tree.

Signed-off-by: Benjamin Cabé <[email protected]>

Author: kartben

doc/_extensions/zephyr/link-roles.py

@@ -9,7 +9,11 @@
 import re
 import subprocess
 from docutils import nodes
+from pathlib import Path
 from sphinx.util import logging
+from typing import Final
+
+ZEPHYR_BASE: Final[str] = Path(__file__).parents[3]
 
 try:
     import west.manifest
@@ -43,6 +47,7 @@ def setup(app):
 
     app.add_config_value("link_roles_manifest_baseurl", None, "env")
     app.add_config_value("link_roles_manifest_project", None, "env")
+    app.add_config_value("link_roles_manifest_project_broken_links_ignore_globs", [], "env")
 
     # The role just creates new nodes based on information in the
     # arguments; its behavior doesn't depend on any other documents.
@@ -59,7 +64,8 @@ def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
         rev = get_github_rev()
         config = inliner.document.settings.env.app.config
         baseurl = config.link_roles_manifest_baseurl
-        trace = f"at '{inliner.parent.source}', line {lineno}"
+        source, line = inliner.reporter.get_source_and_line(lineno)
+        trace = f"at '{source}:{line}'"
 
         m = re.search(r"(.*)\s*<(.*)>", text)
         if m:
@@ -99,6 +105,17 @@ def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
                 f"Configuration value `link_roles_manifest_baseurl` not set\n\t{trace}"
             )
 
+        if module == config.link_roles_manifest_project:
+            p = Path(source).relative_to(inliner.document.settings.env.srcdir)
+            if not any(
+                p.match(glob)
+                for glob in config.link_roles_manifest_project_broken_links_ignore_globs
+            ):
+                if not Path(ZEPHYR_BASE, link).exists():
+                    logger.warning(
+                        f"{link} not found in {config.link_roles_manifest_project} {trace}"
+                    )
+
         url = f"{baseurl}/{format}/{rev}/{link}"
         node = nodes.reference(rawtext, link_text, refuri=url, **options)
         return [node], []

doc/conf.py

@@ -258,6 +258,9 @@
 # -- Options for zephyr.link-roles ----------------------------------------
 
 link_roles_manifest_project = "zephyr"
+link_roles_manifest_project_broken_links_ignore_globs = [
+    "releases/release-notes-[123].*.rst",
+]
 link_roles_manifest_baseurl = "https://github.com/zephyrproject-rtos/zephyr"
 
 # -- Options for notfound.extension ---------------------------------------