Allow to set ansible-output-data templates in the current file.

Author: felixfontein

changelogs/fragments/409-meta.yml

@@ -1,2 +1,2 @@
 minor_changes:
-  - "Add ``ansible-output-meta`` directive that allows to apply meta actions, like resetting previous code blocks for variable references (https://github.com/ansible-community/antsibull-docs/pull/409)."
+  - "Add ``ansible-output-meta`` directive that allows to apply meta actions, like resetting previous code blocks for variable references, or defining templates for ``ansible-output-data`` (https://github.com/ansible-community/antsibull-docs/pull/409)."

docs/ansible-output.md

@@ -240,6 +240,59 @@ above ``yaml`` block as the ``yaml`` block with index 0:
   ...
 ```
 
+### Define template for `ansible-output-data`
+
+The `set-template` action defines a template for all following `ansible-output-data` directives.
+You can use all fields that you can also use for `ansible-output-data` in the template:
+```rst
+.. ansible-output-meta::
+
+  actions:
+    - name: set-template
+      template:
+        # The environment variables will be merged. If a variable is provided here,
+        # you do not have to provide it again in the directive - only if you want to
+        # override its value.
+        env:
+          ANSIBLE_STDOUT_CALLBACK: community.general.tasks_only
+          ANSIBLE_COLLECTIONS_TASKS_ONLY_NUMBER_OF_COLUMNS: "90"
+
+        # Will use this value if not specified in the directive.
+        # If no language is provided in both the template and the directive,
+        # 'ansible-output' will be used.
+        language: console
+
+        # Will use this value if not specified in the directive.
+        prepend_lines: |
+          $ ansible-playbook playbook.yml
+
+        # Will use this value if not specified in the directive.
+        skip_first_lines: 3
+
+        # Will use this value if not specified in the directive.
+        skip_last_lines: 0
+
+        # The variables will be merged. If a varibale is provided here,
+        # you can override it in the directive by specifying a variable
+        # of the same name.
+        variables:
+          hosts:
+            value: localhost
+          tasks:
+            previous_code_block: yaml+jinja
+            previous_code_block_index: -1
+
+        # Will use this value if not specified in the directive.
+        postprocessors: []
+
+        # Will use this value if explicitly set to null/~ in the directive.
+        playbook: |-
+          (some Ansible playbook)
+```
+
+This can be useful to avoid repeating some definitions for multiple code blocks.
+If another `ansible-output-meta` action sets a new template, the previous templates will be thrown away.
+
 ## Post-processing ansible-playbook output
 
 Out of the box, you can post-process the `ansible-playbook` output in some ways:

src/antsibull_docs/ansible_output/load.py

@@ -27,11 +27,14 @@
 from sphinx_antsibull_ext.directive_helper import YAMLDirective
 from sphinx_antsibull_ext.schemas.ansible_output_data import (
     AnsibleOutputData,
+    AnsibleOutputTemplate,
     NonRefPostprocessor,
     PostprocessorNameRef,
+    combine,
 )
 from sphinx_antsibull_ext.schemas.ansible_output_meta import (
     ActionResetPreviousBlocks,
+    ActionSetTemplate,
     AnsibleOutputMeta,
 )
 
@@ -188,12 +191,16 @@ def __init__(
         self.blocks: list[Block] = []
         self.data: _AnsibleOutputDataExt | None = None
         self.previous_blocks: list[CodeBlockInfo] = []
+        self.template = AnsibleOutputTemplate()
 
     def _process_reset_previous_blocks(
         self, action: ActionResetPreviousBlocks  # pylint: disable=unused-argument
     ) -> None:
         self.previous_blocks.clear()
 
+    def _process_set_template(self, action: ActionSetTemplate) -> None:
+        self.template = action.template
+
     def process_meta(
         self,
         meta: AnsibleOutputMeta,
@@ -204,6 +211,8 @@ def process_meta(
         for action in meta.actions:
             if isinstance(action, ActionResetPreviousBlocks):
                 self._process_reset_previous_blocks(action)
+            elif isinstance(action, ActionSetTemplate):
+                self._process_set_template(action)
             else:
                 raise AssertionError("Unknown action")  # pragma: no cover
 
@@ -227,11 +236,25 @@ def process_special_block(
             self.errors.append(Error(self.path, line, col, message))
         if "antsibull-other-data" in block.attributes:
             if directive == "ansible-output-data":
-                self.data = _AnsibleOutputDataExt(
-                    data=block.attributes["antsibull-other-data"],
-                    line=block.row_offset + 1,
-                    col=block.col_offset + 1,
-                )
+                try:
+                    data = combine(
+                        data=block.attributes["antsibull-other-data"],
+                        template=self.template,
+                    )
+                    self.data = _AnsibleOutputDataExt(
+                        data=data,
+                        line=block.row_offset + 1,
+                        col=block.col_offset + 1,
+                    )
+                except ValueError as exc:
+                    self.errors.append(
+                        Error(
+                            self.path,
+                            block.row_offset + 1,
+                            block.col_offset + 1,
+                            str(exc),
+                        )
+                    )
             if directive == "ansible-output-meta":
                 self.process_meta(
                     block.attributes["antsibull-other-data"],
@@ -249,23 +272,24 @@ def _add_block(
         env.update(data.data.env)
         postprocessors = []
         error = False
-        for postprocessor in data.data.postprocessors:
-            if isinstance(postprocessor, PostprocessorNameRef):
-                ref = postprocessor.name
-                try:
-                    postprocessor = self.environment.global_postprocessors[ref]
-                except KeyError:
-                    self.errors.append(
-                        Error(
-                            self.path,
-                            data.line,
-                            data.col,
-                            f"No global postprocessor of name {ref!r} defined",
+        if data.data.postprocessors:
+            for postprocessor in data.data.postprocessors:
+                if isinstance(postprocessor, PostprocessorNameRef):
+                    ref = postprocessor.name
+                    try:
+                        postprocessor = self.environment.global_postprocessors[ref]
+                    except KeyError:
+                        self.errors.append(
+                            Error(
+                                self.path,
+                                data.line,
+                                data.col,
+                                f"No global postprocessor of name {ref!r} defined",
+                            )
                         )
-                    )
-                    error = True
-                    continue
-            postprocessors.append(postprocessor)
+                        error = True
+                        continue
+                postprocessors.append(postprocessor)
         if error:
             return
         self.blocks.append(

src/antsibull_docs/ansible_output/process.py

@@ -61,6 +61,9 @@ def _get_variable_value(
 def _compose_playbook(
     data: AnsibleOutputData, *, previous_blocks: list[CodeBlockInfo]
 ) -> str:
+    if data.playbook is None:
+        raise AssertionError("playbook cannot be None at this point")
+
     if all(s not in data.playbook for s in ("@{%", "@{{", "@{#")):
         return data.playbook
 
@@ -221,8 +224,8 @@ async def _compute_code_block_content(
         flog.notice("Post-process result")
         lines = _massage_stdout(
             stdout,
-            skip_first_lines=block.data.skip_first_lines,
-            skip_last_lines=block.data.skip_last_lines,
+            skip_first_lines=block.data.skip_first_lines or 0,
+            skip_last_lines=block.data.skip_last_lines or 0,
             prepend_lines=block.data.prepend_lines,
         )
         for postprocessor in block.merged_postprocessors:

src/sphinx_antsibull_ext/schemas/ansible_output_data.py

@@ -50,15 +50,15 @@ class PostprocessorNameRef(p.BaseModel):
 NonRefPostprocessor = t.Union[PostprocessorCLI]
 
 
-class AnsibleOutputData(p.BaseModel):
-    playbook: str
+class AnsibleOutputTemplate(p.BaseModel):
+    playbook: t.Optional[str] = None
     env: dict[str, str] = {}
-    prepend_lines: str = ""
-    language: str = "ansible-output"
+    prepend_lines: t.Optional[str] = None
+    language: t.Optional[str] = None
     variables: dict[str, VariableSource] = {}
-    skip_first_lines: int = 0
-    skip_last_lines: int = 0
-    postprocessors: list[Postprocessor] = []
+    skip_first_lines: t.Optional[int] = None
+    skip_last_lines: t.Optional[int] = None
+    postprocessors: t.Optional[list[Postprocessor]] = None
 
     @p.field_validator("env", mode="before")
     @classmethod
@@ -73,3 +73,39 @@ def convert_dict_values(cls, obj):
                 if isinstance(v, int):
                     obj[k] = str(v)
         return obj
+
+
+class AnsibleOutputData(AnsibleOutputTemplate):
+    playbook: t.Optional[str]  # no default
+
+
+_T = t.TypeVar("_T")
+
+
+def _coalesce(*values: _T | None) -> _T | None:
+    for value in values:
+        if value is not None:
+            return value
+    return None
+
+
+def combine(
+    *, template: AnsibleOutputTemplate, data: AnsibleOutputData
+) -> AnsibleOutputData:
+    playbook = _coalesce(data.playbook, template.playbook)
+    if playbook is None:
+        raise ValueError("Cannot use template's playbook since that is not set")
+    env = template.env.copy()
+    env.update(data.env)
+    variables = template.variables.copy()
+    variables.update(data.variables)
+    return AnsibleOutputData(
+        playbook=playbook,
+        env=env,
+        prepend_lines=data.prepend_lines or template.prepend_lines,
+        language=data.language or template.language or "ansible-output",
+        variables=variables,
+        skip_first_lines=_coalesce(data.skip_first_lines, template.skip_first_lines),
+        skip_last_lines=_coalesce(data.skip_last_lines, template.skip_last_lines),
+        postprocessors=_coalesce(data.postprocessors, template.postprocessors),
+    )

src/sphinx_antsibull_ext/schemas/ansible_output_meta.py

@@ -11,14 +11,23 @@
 
 import pydantic as p
 
+from .ansible_output_data import AnsibleOutputTemplate
+
 
 class ActionResetPreviousBlocks(p.BaseModel):
     model_config = p.ConfigDict(frozen=True, extra="forbid", validate_default=True)
 
     name: t.Literal["reset-previous-blocks"]
 
 
-AnsibleOutputAction = t.Union[ActionResetPreviousBlocks]
+class ActionSetTemplate(p.BaseModel):
+    model_config = p.ConfigDict(frozen=True, extra="forbid", validate_default=True)
+
+    name: t.Literal["set-template"]
+    template: AnsibleOutputTemplate
+
+
+AnsibleOutputAction = t.Union[ActionResetPreviousBlocks, ActionSetTemplate]
 
 
 class AnsibleOutputMeta(p.BaseModel):