Extra docs: generate Ansible outputs with 'antsibull-docs ansible-output'

.github/workflows/docs.yml

@@ -0,0 +1,34 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+name: nox
+'on':
+  push:
+    branches:
+      - main
+      - stable-*
+    paths:
+      - docs/**
+  pull_request:
+    paths:
+      - docs/**
+  # Run CI once per day (at 08:00 UTC)
+  schedule:
+    - cron: '0 8 * * *'
+  workflow_dispatch:
+
+jobs:
+  nox:
+    runs-on: ubuntu-latest
+    name: "Validate generated Ansible output"
+    steps:
+      - name: Check out collection
+        uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+      - name: Run nox
+        uses: ansible-community/antsibull-nox@main
+        with:
+          sessions: ansible-output

docs/docsite/config.yml

@@ -5,3 +5,13 @@
 
 changelog:
   write_changelog: true
+
+ansible_output:
+  global_env:
+    ANSIBLE_STDOUT_CALLBACK: community.general.tasks_only
+    ANSIBLE_COLLECTIONS_TASKS_ONLY_NUMBER_OF_COLUMNS: 90
+  global_postprocessors:
+    reformat-yaml:
+      command:
+        - python
+        - docs/docsite/reformat-yaml.py

docs/docsite/reformat-yaml.py

@@ -0,0 +1,27 @@
+#!/usr/bin/env python
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import sys
+from io import StringIO
+
+from ruamel.yaml import YAML
+
+
+def main() -> None:
+    yaml = YAML(typ='rt')
+    yaml.indent(mapping=2, sequence=4, offset=2)
+    yaml.allow_duplicate_keys = True
+
+    # Load
+    data = yaml.load(sys.stdin)
+
+    # Dump
+    sio = StringIO()
+    yaml.dump(data, sio)
+    print(sio.getvalue().rstrip('\n'))
+
+
+if __name__ == "__main__":
+    main()

docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-keep_keys.rst

@@ -13,6 +13,34 @@ Use the filter :ansplugin:`community.general.keep_keys#filter` if you have a lis
 
 Let us use the below list in the following examples:
 
+.. ansible-output-meta::
+
+  actions:
+    - name: reset-previous-blocks
+    - name: set-template
+      template:
+        env:
+          ANSIBLE_CALLBACK_RESULT_FORMAT: yaml
+        variables:
+          data:
+            previous_code_block: yaml
+            previous_code_block_index: 0
+          computation:
+            previous_code_block: yaml+jinja
+        postprocessors:
+          - name: reformat-yaml
+        language: yaml
+        skip_first_lines: 2
+        playbook: |-
+          - hosts: localhost
+            gather_facts: false
+            tasks:
+              - vars:
+                  @{{ data | indent(8) }}@
+                  @{{ computation | indent(8) }}@
+                ansible.builtin.debug:
+                  var: result
+
 .. code-block:: yaml
 
    input:
@@ -37,24 +65,48 @@ Let us use the below list in the following examples:
 
 gives
 
+.. ansible-output-data::
+
+    playbook: ~
+
 .. code-block:: yaml
    :emphasize-lines: 1-
 
    result:
-     - {k0_x0: A0, k1_x1: B0}
-     - {k0_x0: A1, k1_x1: B1}
+     - k0_x0: A0
+       k1_x1: B0
+     - k0_x0: A1
+       k1_x1: B1
 
 
 .. versionadded:: 9.1.0
 
 * The results of the below examples 1-5 are all the same:
 
+.. ansible-output-data::
+
+    playbook: |-
+      - hosts: localhost
+        gather_facts: false
+        tasks:
+          - vars:
+              @{{ data | indent(8) }}@
+
+              # I picked one of the examples
+              mp: equal
+              target: ['k0_x0', 'k1_x1']
+              result: "{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}"
+            ansible.builtin.debug:
+              var: result
+
 .. code-block:: yaml
    :emphasize-lines: 1-
 
    result:
-     - {k0_x0: A0, k1_x1: B0}
-     - {k0_x0: A1, k1_x1: B1}
+     - k0_x0: A0
+       k1_x1: B0
+     - k0_x0: A1
+       k1_x1: B1
 
 
 1. Match keys that equal any of the items in the target.
@@ -105,12 +157,28 @@ gives
 
 * The results of the below examples 6-9 are all the same:
 
+.. ansible-output-data::
+
+    playbook: |-
+      - hosts: localhost
+        gather_facts: false
+        tasks:
+          - vars:
+              @{{ data | indent(8) }}@
+
+              # I picked one of the examples
+              mp: equal
+              target: k0_x0
+              result: "{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}"
+            ansible.builtin.debug:
+              var: result
+
 .. code-block:: yaml
    :emphasize-lines: 1-
 
    result:
-     - {k0_x0: A0}
-     - {k0_x0: A1}
+     - k0_x0: A0
+     - k0_x0: A1
 
 
 6. Match keys that equal the target.
@@ -148,4 +216,3 @@ gives
    mp: regex
    target: ^.*0_x.*$
    result: "{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}"
-

docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-remove_keys.rst

@@ -13,6 +13,34 @@ Use the filter :ansplugin:`community.general.remove_keys#filter` if you have a l
 
 Let us use the below list in the following examples:
 
+.. ansible-output-meta::
+
+  actions:
+    - name: reset-previous-blocks
+    - name: set-template
+      template:
+        env:
+          ANSIBLE_CALLBACK_RESULT_FORMAT: yaml
+        variables:
+          data:
+            previous_code_block: yaml
+            previous_code_block_index: 0
+          computation:
+            previous_code_block: yaml+jinja
+        postprocessors:
+          - name: reformat-yaml
+        language: yaml
+        skip_first_lines: 2
+        playbook: |-
+          - hosts: localhost
+            gather_facts: false
+            tasks:
+              - vars:
+                  @{{ data | indent(8) }}@
+                  @{{ computation | indent(8) }}@
+                ansible.builtin.debug:
+                  var: result
+
 .. code-block:: yaml
 
    input:
@@ -37,27 +65,51 @@ Let us use the below list in the following examples:
 
 gives
 
+.. ansible-output-data::
+
+    playbook: ~
+
 .. code-block:: yaml
    :emphasize-lines: 1-
 
    result:
-     - k2_x2: [C0]
+     - k2_x2:
+         - C0
        k3_x3: foo
-     - k2_x2: [C1]
+     - k2_x2:
+         - C1
        k3_x3: bar
 
 
 .. versionadded:: 9.1.0
 
 * The results of the below examples 1-5 are all the same:
 
+.. ansible-output-data::
+
+    playbook: |-
+      - hosts: localhost
+        gather_facts: false
+        tasks:
+          - vars:
+              @{{ data | indent(8) }}@
+
+              # I picked one of the examples
+              mp: equal
+              target: ['k0_x0', 'k1_x1']
+              result: "{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}"
+            ansible.builtin.debug:
+              var: result
+
 .. code-block:: yaml
    :emphasize-lines: 1-
 
    result:
-     - k2_x2: [C0]
+     - k2_x2:
+         - C0
        k3_x3: foo
-     - k2_x2: [C1]
+     - k2_x2:
+         - C1
        k3_x3: bar
 
 
@@ -109,15 +161,33 @@ gives
 
 * The results of the below examples 6-9 are all the same:
 
+.. ansible-output-data::
+
+    playbook: |-
+      - hosts: localhost
+        gather_facts: false
+        tasks:
+          - vars:
+              @{{ data | indent(8) }}@
+
+              # I picked one of the examples
+              mp: equal
+              target: k0_x0
+              result: "{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}"
+            ansible.builtin.debug:
+              var: result
+
 .. code-block:: yaml
    :emphasize-lines: 1-
 
    result:
      - k1_x1: B0
-       k2_x2: [C0]
+       k2_x2:
+         - C0
        k3_x3: foo
      - k1_x1: B1
-       k2_x2: [C1]
+       k2_x2:
+         - C1
        k3_x3: bar
 
 
@@ -156,4 +226,3 @@ gives
    mp: regex
    target: ^.*0_x.*$
    result: "{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}"
-