Support file level prefaces (#180)

Author: felix-hilden

docs/src/reference.rst

@@ -14,12 +14,12 @@ Configuration
 -------------
 .. confval:: codeautolink_autodoc_inject
 
-   Type: ``bool``. Inject a :rst:dir:`autolink-examples` table
+   Type: ``bool``. Inject an :rst:dir:`autolink-examples` table
    to the end of all autodoc definitions. Defaults to :code:`False`.
 
 .. confval:: codeautolink_global_preface
 
-   Type: ``str``. Include a :rst:dir:`autolink-preface` before all blocks.
+   Type: ``str``. Include an :rst:dir:`autolink-preface` before all blocks.
    When other prefaces or concatenated sources are used in a block,
    the global preface is included first and only once.
 
@@ -117,11 +117,25 @@ Directives
 
 .. rst:directive:: .. autolink-preface:: [code]
 
-   Include a hidden preface in the next code block.
-   The next block consumes this directive even if it is not
-   processed (e.g. non-Python blocks) to avoid placement confusion.
+   Include a hidden preface before a code block.
    A multiline preface can be written in the content portion of the directive.
-   Prefaces are included in block concatenation.
+   Prefaces are preserved in block concatenation, and are added to the source
+   in the following order: :confval:`codeautolink_global_preface` > file preface
+   > :rst:dir:`autolink-concat` sources (with their block prefaces)
+   > block prefaces > block source.
+
+   .. rubric:: Options
+
+   .. rst:directive:option:: level
+      :type: preface level
+
+      - "next" - add preface only to the next block (default).
+        Multiple prefaces are combined, and the next block consumes this
+        directive even if it's not processed (e.g. non-Python blocks)
+        to avoid placement confusion.
+      - "file" - set a preface for all blocks in the current file, placed
+        after  but before block-level
+        prefaces.
 
 .. rst:directive:: .. autolink-skip:: [level]
 

docs/src/release_notes.rst

@@ -14,6 +14,8 @@ Unreleased
 - Fix attribute and call after walrus leading parser error (:issue:`174`)
 - Fix parsing error in doctest blocks with empty lines (:issue:`176`)
 - Improve error message on uncaught parsing errors (:issue:`177`)
+- Add ``level`` argument to :rst:dir:`autolink-preface` to support
+  file-level prefaces (:issue:`180`)
 
 0.17.0 (2025-02-18)
 -------------------

src/sphinx_codeautolink/extension/block.py

@@ -123,12 +123,13 @@ def __init__(
         relative_path = Path(self.document["source"]).relative_to(source_dir)
         self.current_document = str(relative_path.with_suffix(""))
         self.global_preface = global_preface
+        self.file_preface = []
+        self.prefaces = []
         self.transformers = BUILTIN_BLOCKS.copy()
         self.transformers.update(custom_blocks)
         self.valid_blocks = self.transformers.keys()
         self.title_stack = []
         self.current_refid = None
-        self.prefaces = []
         self.concat_global = concat_default
         self.concat_section = False
         self.concat_sources = []
@@ -153,7 +154,16 @@ def unknown_visit(self, node) -> None:
                 self.concat_global = node.mode == "on"
             node.parent.remove(node)
         elif isinstance(node, PrefaceMarker):
-            self.prefaces.extend(node.content.split("\n"))
+            lines = node.content.split("\n") or []
+            if node.level == "next":
+                self.prefaces.extend(lines)
+            elif node.level == "file":
+                self.file_preface = lines
+            else:
+                msg = f"Invalid preface argument: `{node.level}`"
+                logger.error(
+                    msg, type=warn_type, subtype="invalid_argument", location=node
+                )
             node.parent.remove(node)
         elif isinstance(node, SkipMarker):
             if node.level not in ("next", "section", "file", "off"):
@@ -243,31 +253,45 @@ def parse_source(  # noqa: C901,PLR0912
             clean_source = source
         transform.source = source
 
-        modified_source = "\n".join(
-            self.global_preface + self.concat_sources + prefaces + [clean_source]
+        full_source = "\n".join(
+            self.global_preface
+            + self.file_preface
+            + self.concat_sources
+            + prefaces
+            + [clean_source]
         )
         try:
-            names = parse_names(modified_source, node)
+            names = parse_names(full_source, node)
         except SyntaxError as e:
             if language == "default" and not self.warn_default_parse_fail:
                 return
 
             show_source = self._format_source_for_error(
-                self.global_preface, self.concat_sources, prefaces, transform.source
+                self.global_preface,
+                self.file_preface,
+                self.concat_sources,
+                prefaces,
+                transform.source,
             )
             msg = self._parsing_error_msg(e, language, show_source)
             logger.warning(msg, type=warn_type, subtype="parse_block", location=node)
             return
         except Exception as e:
             show_source = self._format_source_for_error(
-                self.global_preface, self.concat_sources, prefaces, transform.source
+                self.global_preface,
+                self.file_preface,
+                self.concat_sources,
+                prefaces,
+                transform.source,
             )
             msg = self._parsing_error_msg(e, language, show_source)
             raise type(e)(msg) from e
 
-        if prefaces or self.concat_sources or self.global_preface:
+        if prefaces or self.concat_sources or self.global_preface or self.file_preface:
             concat_lens = [s.count("\n") + 1 for s in self.concat_sources]
-            hidden_len = len(prefaces) + sum(concat_lens) + len(self.global_preface)
+            hidden_len = len(prefaces + self.global_preface + self.file_preface) + sum(
+                concat_lens
+            )
             for name in names:
                 name.lineno -= hidden_len
                 name.end_lineno -= hidden_len
@@ -281,16 +305,26 @@ def parse_source(  # noqa: C901,PLR0912
     @staticmethod
     def _format_source_for_error(
         global_preface: list[str],
+        file_preface: list[str],
         concat_sources: list[str],
         prefaces: list[str],
         source: str,
     ) -> str:
-        lines = global_preface + concat_sources + prefaces + source.split("\n")
+        lines = (
+            global_preface
+            + file_preface
+            + concat_sources
+            + prefaces
+            + source.split("\n")
+        )
         guides = [""] * len(lines)
         ix = 0
         if global_preface:
-            guides[0] = "global preface:"
+            guides[ix] = "global preface:"
             ix += len(global_preface)
+        if file_preface:
+            guides[ix] = "file preface:"
+            ix += len(concat_sources)
         if concat_sources:
             guides[ix] = "concatenations:"
             ix += len(concat_sources)

src/sphinx_codeautolink/extension/directive.py

@@ -77,9 +77,10 @@ def run(self):
 class PrefaceMarker(nodes.Element):
     """Marker for :class:`Preface`."""
 
-    def __init__(self, content: str) -> None:
+    def __init__(self, content: str, level: str) -> None:
         super().__init__()
         self.content = content
+        self.level = level
 
     def copy(self):
         """Copy element."""
@@ -93,11 +94,13 @@ class Preface(Directive):
     required_arguments = 0
     optional_arguments = 1
     final_argument_whitespace = True
+    option_spec: ClassVar = {"level": directives.unchanged}
 
     def run(self):
         """Insert :class:`PrefaceMarker`."""
         lines = list(self.arguments) + list(self.content)
-        return [PrefaceMarker("\n".join(lines))]
+        level = self.options.get("level", "next")
+        return [PrefaceMarker("\n".join(lines), level)]
 
 
 class SkipMarker(nodes.Element):

tests/extension/fail/preface_invalid_arg.txt

@@ -0,0 +1,8 @@
+# split
+Test project
+============
+
+.. autolink-preface:: import lib
+   :level: whatevs
+
+.. automodule:: test_project

tests/extension/fail/ref_invalid_syntax_complex.txt

@@ -3,6 +3,9 @@ codeautolink_global_preface = "import test_project"
 Test project
 ============
 
+.. autolink-preface:: import test_project
+   :level: file
+
 .. autolink-concat::
 .. code:: python
 

tests/extension/ref/preface_document.txt

@@ -0,0 +1,26 @@
+test_project.Foo
+test_project.bar
+# split
+# split
+Test project
+============
+
+.. autolink-preface:: import test_project
+   :level: file
+
+.. code:: python
+
+   test_project.Foo()
+
+.. code:: python
+
+   test_project.bar()
+
+.. autolink-preface::
+   :level: file
+
+.. code:: python
+
+   test_project.baz()
+
+.. automodule:: test_project