doc: extensions: Add line reference support to zephyr_file/zephyr_module

Enhance the zephyr_file link role to support referencing specific lines
or line ranges in files.
This change allows users to link to exact locations within a file
using GitHub-style line references.

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

doc/_extensions/zephyr/link-roles.py

@@ -84,6 +84,12 @@ def role(
             link_text = text
             link = text
 
+        line_ref = ""
+        line_match = re.search(r"(.+?)(?:#(L\d+(?:-L\d+)?))?$", link)
+        if line_match and line_match.group(2):
+            link = line_match.group(1)
+            line_ref = f"?plain=1#{line_match.group(2)}"
+
         module_match = re.search(r"(.+?):\s*(.+)", link)
         if module_match:
             module = module_match.group(1).strip()
@@ -124,7 +130,7 @@ def role(
                     f"{link} not found in {config.link_roles_manifest_project} {trace}"
                 )
 
-        url = f"{baseurl}/{format}/{rev}/{link}"
+        url = f"{baseurl}/{format}/{rev}/{link}{line_ref}"
         node = nodes.reference(rawtext, link_text, refuri=url, **options)
         return [node], []
 

doc/contribute/documentation/guidelines.rst

@@ -942,7 +942,26 @@ very file can be done using the :rst:role:`zephyr_file` role.
 
       Check out :zephyr_file:`doc/contribute/documentation/guidelines.rst` for more information.
 
-You may use the :rst:role:`zephyr_raw` role instead if you want to reference the "raw" content.
+   You can reference specific lines or line ranges in a file by appending :samp:`#L{line_number}` or
+   :samp:`#L{start_line}-L{end_line}` to the file path::
+
+      See :zephyr_file:`doc/contribute/documentation/guidelines.rst#L3` for the main heading of
+      this document.
+
+   Will render as:
+
+      See :zephyr_file:`doc/contribute/documentation/guidelines.rst#L3` for the main heading of
+      this document.
+
+   The role automatically verifies that the referenced file exists in the Zephyr tree and will
+   generate a warning during documentation build if the file is not found.
+
+   .. note::
+
+      Use the line references sparingly as keeping them accurate over time can be challenging as the
+      content of the linked file is subject to change.
+
+   You may use the :rst:role:`zephyr_raw` role instead if you want to reference the "raw" content.
 
 .. rst:role:: zephyr_raw
 
@@ -964,6 +983,7 @@ You may use the :rst:role:`zephyr_raw` role instead if you want to reference the
 
          Check out :module_file:`hal_stm32:CMakeLists.txt` for more information.
 
+   Similar to :rst:role:`zephyr_file`, you can reference specific lines or line ranges in a file.
 
 Cross-referencing GitHub issues and pull requests
 =================================================