Release 12.2.0.

lxc_container: replace subprocess.Popen() with run_command() (#11204)

* lxc_container: replace subprocess.Popen() with run_command()

* Update plugins/modules/lxc_container.py



* add changelog frag

* retain Popen logic in module_utils

* Update plugins/module_utils/_lxc.py



---------


(cherry picked from commit 6ae47590cd)

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>
Co-authored-by: Felix Fontein <felix@fontein.de>

.azure-pipelines/azure-pipelines.yml

@@ -29,7 +29,6 @@ schedules:
     always: true
     branches:
       include:
-        - stable-12
         - stable-11
   - cron: 0 11 * * 0
     displayName: Weekly (old stable branches)
@@ -57,6 +56,19 @@ pool: Standard
 
 stages:
 ### Sanity
+  - stage: Sanity_devel
+    displayName: Sanity devel
+    dependsOn: []
+    jobs:
+      - template: templates/matrix.yml
+        parameters:
+          nameFormat: Test {0}
+          testFormat: devel/sanity/{0}
+          targets:
+            - test: 1
+            - test: 2
+            - test: 3
+            - test: 4
   - stage: Sanity_2_20
     displayName: Sanity 2.20
     dependsOn: []
@@ -97,6 +109,21 @@ stages:
             - test: 3
             - test: 4
 ### Units
+  - stage: Units_devel
+    displayName: Units devel
+    dependsOn: []
+    jobs:
+      - template: templates/matrix.yml
+        parameters:
+          nameFormat: Python {0}
+          testFormat: devel/units/{0}/1
+          targets:
+            - test: 3.9
+            - test: '3.10'
+            - test: '3.11'
+            - test: '3.12'
+            - test: '3.13'
+            - test: '3.14'
   - stage: Units_2_20
     displayName: Units 2.20
     dependsOn: []
@@ -107,11 +134,8 @@ stages:
           testFormat: 2.20/units/{0}/1
           targets:
             - test: 3.9
-            - test: '3.10'
-            - test: '3.11'
-            - test: '3.12'
-            - test: '3.13'
-            - test: '3.14'
+            - test: "3.12"
+            - test: "3.14"
   - stage: Units_2_19
     displayName: Units 2.19
     dependsOn: []
@@ -138,13 +162,13 @@ stages:
             - test: "3.13"
 
 ## Remote
-  - stage: Remote_2_20_extra_vms
-    displayName: Remote 2.20 extra VMs
+  - stage: Remote_devel_extra_vms
+    displayName: Remote devel extra VMs
     dependsOn: []
     jobs:
       - template: templates/matrix.yml
         parameters:
-          testFormat: 2.20/{0}
+          testFormat: devel/{0}
           targets:
             - name: Alpine 3.22
               test: alpine/3.22
@@ -156,6 +180,28 @@ stages:
               test: ubuntu/24.04
           groups:
             - vm
+  - stage: Remote_devel
+    displayName: Remote devel
+    dependsOn: []
+    jobs:
+      - template: templates/matrix.yml
+        parameters:
+          testFormat: devel/{0}
+          targets:
+            - name: macOS 15.3
+              test: macos/15.3
+            - name: RHEL 10.0
+              test: rhel/10.0
+            - name: RHEL 9.6
+              test: rhel/9.6
+            - name: FreeBSD 14.3
+              test: freebsd/14.3
+            - name: FreeBSD 13.5
+              test: freebsd/13.5
+          groups:
+            - 1
+            - 2
+            - 3
   - stage: Remote_2_20
     displayName: Remote 2.20
     dependsOn: []
@@ -164,16 +210,10 @@ stages:
         parameters:
           testFormat: 2.20/{0}
           targets:
-            - name: macOS 15.3
-              test: macos/15.3
-            - name: RHEL 10.1
-              test: rhel/10.1
-            - name: RHEL 9.7
-              test: rhel/9.7
+            - name: RHEL 10.0
+              test: rhel/10.0
             - name: FreeBSD 14.3
               test: freebsd/14.3
-            - name: FreeBSD 13.5
-              test: freebsd/13.5
           groups:
             - 1
             - 2
@@ -186,8 +226,10 @@ stages:
         parameters:
           testFormat: 2.19/{0}
           targets:
-            - name: RHEL 10.1
-              test: rhel/10.1
+            - name: RHEL 9.5
+              test: rhel/9.5
+            - name: RHEL 10.0
+              test: rhel/10.0
             - name: FreeBSD 14.2
               test: freebsd/14.2
           groups:
@@ -202,8 +244,10 @@ stages:
         parameters:
           testFormat: 2.18/{0}
           targets:
-            # - name: macOS 14.3
-            #   test: macos/14.3
+            - name: macOS 14.3
+              test: macos/14.3
+            - name: RHEL 9.4
+              test: rhel/9.4
             - name: FreeBSD 14.1
               test: freebsd/14.1
           groups:
@@ -212,6 +256,26 @@ stages:
             - 3
 
 ### Docker
+  - stage: Docker_devel
+    displayName: Docker devel
+    dependsOn: []
+    jobs:
+      - template: templates/matrix.yml
+        parameters:
+          testFormat: devel/linux/{0}
+          targets:
+            - name: Fedora 42
+              test: fedora42
+            - name: Alpine 3.22
+              test: alpine322
+            - name: Ubuntu 22.04
+              test: ubuntu2204
+            - name: Ubuntu 24.04
+              test: ubuntu2404
+          groups:
+            - 1
+            - 2
+            - 3
   - stage: Docker_2_20
     displayName: Docker 2.20
     dependsOn: []
@@ -224,10 +288,6 @@ stages:
               test: fedora42
             - name: Alpine 3.22
               test: alpine322
-            - name: Ubuntu 22.04
-              test: ubuntu2204
-            - name: Ubuntu 24.04
-              test: ubuntu2404
           groups:
             - 1
             - 2
@@ -268,13 +328,13 @@ stages:
             - 3
 
 ### Community Docker
-  - stage: Docker_community_2_20
-    displayName: Docker (community images) 2.20
+  - stage: Docker_community_devel
+    displayName: Docker (community images) devel
     dependsOn: []
     jobs:
       - template: templates/matrix.yml
         parameters:
-          testFormat: 2.20/linux-community/{0}
+          testFormat: devel/linux-community/{0}
           targets:
             - name: Debian 11 Bullseye
               test: debian-bullseye/3.9
@@ -283,7 +343,7 @@ stages:
             - name: Debian 13 Trixie
               test: debian-13-trixie/3.13
             - name: ArchLinux
-              test: archlinux/3.14
+              test: archlinux/3.13
           groups:
             - 1
             - 2
@@ -291,6 +351,18 @@ stages:
 
 ### Generic
 # Right now all generic tests are disabled. Uncomment when at least one of them is re-enabled.
+#  - stage: Generic_devel
+#    displayName: Generic devel
+#    dependsOn: []
+#    jobs:
+#      - template: templates/matrix.yml
+#        parameters:
+#          nameFormat: Python {0}
+#          testFormat: devel/generic/{0}/1
+#          targets:
+#            - test: '3.9'
+#            - test: '3.12'
+#            - test: '3.14'
 #  - stage: Generic_2_20
 #    displayName: Generic 2.20
 #    dependsOn: []
@@ -300,8 +372,7 @@ stages:
 #          nameFormat: Python {0}
 #          testFormat: 2.20/generic/{0}/1
 #          targets:
-#            - test: '3.9'
-#            - test: '3.12'
+#            - test: '3.10'
 #            - test: '3.14'
 #  - stage: Generic_2_19
 #    displayName: Generic 2.19
@@ -329,21 +400,26 @@ stages:
   - stage: Summary
     condition: succeededOrFailed()
     dependsOn:
+      - Sanity_devel
       - Sanity_2_20
       - Sanity_2_19
       - Sanity_2_18
+      - Units_devel
       - Units_2_20
       - Units_2_19
       - Units_2_18
-      - Remote_2_20_extra_vms
+      - Remote_devel_extra_vms
+      - Remote_devel
       - Remote_2_20
       - Remote_2_19
       - Remote_2_18
+      - Docker_devel
       - Docker_2_20
       - Docker_2_19
       - Docker_2_18
-      - Docker_community_2_20
+      - Docker_community_devel
 # Right now all generic tests are disabled. Uncomment when at least one of them is re-enabled.
+#      - Generic_devel
 #      - Generic_2_20
 #      - Generic_2_19
 #      - Generic_2_18

.azure-pipelines/scripts/combine-coverage.py

@@ -11,8 +11,7 @@ Keep in mind that Azure Pipelines does not enforce unique job display names (onl
 It is up to pipeline authors to avoid name collisions when deviating from the recommended format.
 """
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
 
 import os
 import re
@@ -24,12 +23,12 @@ def main():
     """Main program entry point."""
     source_directory = sys.argv[1]
 
-    if '/ansible_collections/' in os.getcwd():
+    if "/ansible_collections/" in os.getcwd():
         output_path = "tests/output"
     else:
         output_path = "test/results"
 
-    destination_directory = os.path.join(output_path, 'coverage')
+    destination_directory = os.path.join(output_path, "coverage")
 
     if not os.path.exists(destination_directory):
         os.makedirs(destination_directory)
@@ -38,27 +37,27 @@ def main():
     count = 0
 
     for name in os.listdir(source_directory):
-        match = re.search('^Coverage (?P<attempt>[0-9]+) (?P<label>.+)$', name)
-        label = match.group('label')
-        attempt = int(match.group('attempt'))
+        match = re.search("^Coverage (?P<attempt>[0-9]+) (?P<label>.+)$", name)
+        label = match.group("label")
+        attempt = int(match.group("attempt"))
         jobs[label] = max(attempt, jobs.get(label, 0))
 
     for label, attempt in jobs.items():
-        name = 'Coverage {attempt} {label}'.format(label=label, attempt=attempt)
+        name = "Coverage {attempt} {label}".format(label=label, attempt=attempt)
         source = os.path.join(source_directory, name)
         source_files = os.listdir(source)
 
         for source_file in source_files:
             source_path = os.path.join(source, source_file)
-            destination_path = os.path.join(destination_directory, source_file + '.' + label)
+            destination_path = os.path.join(destination_directory, source_file + "." + label)
             print('"%s" -> "%s"' % (source_path, destination_path))
             shutil.copyfile(source_path, destination_path)
             count += 1
 
-    print('Coverage file count: %d' % count)
-    print('##vso[task.setVariable variable=coverageFileCount]%d' % count)
-    print('##vso[task.setVariable variable=outputPath]%s' % output_path)
+    print("Coverage file count: %d" % count)
+    print("##vso[task.setVariable variable=coverageFileCount]%d" % count)
+    print("##vso[task.setVariable variable=outputPath]%s" % output_path)
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     main()

.azure-pipelines/scripts/publish-codecov.py

@@ -34,8 +34,8 @@ class Args:
 
 def parse_args() -> Args:
     parser = argparse.ArgumentParser()
-    parser.add_argument('-n', '--dry-run', action='store_true')
-    parser.add_argument('path', type=pathlib.Path)
+    parser.add_argument("-n", "--dry-run", action="store_true")
+    parser.add_argument("path", type=pathlib.Path)
 
     args = parser.parse_args()
 
@@ -48,12 +48,14 @@ def parse_args() -> Args:
 
 def process_files(directory: pathlib.Path) -> t.Tuple[CoverageFile, ...]:
     processed = []
-    for file in directory.joinpath('reports').glob('coverage*.xml'):
-        name = file.stem.replace('coverage=', '')
+    for file in directory.joinpath("reports").glob("coverage*.xml"):
+        name = file.stem.replace("coverage=", "")
 
         # Get flags from name
-        flags = name.replace('-powershell', '').split('=')  # Drop '-powershell' suffix
-        flags = [flag if not flag.startswith('stub') else flag.split('-')[0] for flag in flags]  # Remove "-01" from stub files
+        flags = name.replace("-powershell", "").split("=")  # Drop '-powershell' suffix
+        flags = [
+            flag if not flag.startswith("stub") else flag.split("-")[0] for flag in flags
+        ]  # Remove "-01" from stub files
 
         processed.append(CoverageFile(name, file, flags))
 
@@ -64,14 +66,16 @@ def upload_files(codecov_bin: pathlib.Path, files: t.Tuple[CoverageFile, ...], d
     for file in files:
         cmd = [
             str(codecov_bin),
-            '--name', file.name,
-            '--file', str(file.path),
+            "--name",
+            file.name,
+            "--file",
+            str(file.path),
         ]
         for flag in file.flags:
-            cmd.extend(['--flags', flag])
+            cmd.extend(["--flags", flag])
 
         if dry_run:
-            print(f'DRY-RUN: Would run command: {cmd}')
+            print(f"DRY-RUN: Would run command: {cmd}")
             continue
 
         subprocess.run(cmd, check=True)
@@ -79,11 +83,11 @@ def upload_files(codecov_bin: pathlib.Path, files: t.Tuple[CoverageFile, ...], d
 
 def download_file(url: str, dest: pathlib.Path, flags: int, dry_run: bool = False) -> None:
     if dry_run:
-        print(f'DRY-RUN: Would download {url} to {dest} and set mode to {flags:o}')
+        print(f"DRY-RUN: Would download {url} to {dest} and set mode to {flags:o}")
         return
 
     with urllib.request.urlopen(url) as resp:
-        with dest.open('w+b') as f:
+        with dest.open("w+b") as f:
             # Read data in chunks rather than all at once
             shutil.copyfileobj(resp, f, 64 * 1024)
 
@@ -92,14 +96,14 @@ def download_file(url: str, dest: pathlib.Path, flags: int, dry_run: bool = Fals
 
 def main():
     args = parse_args()
-    url = 'https://ansible-ci-files.s3.amazonaws.com/codecov/linux/codecov'
-    with tempfile.TemporaryDirectory(prefix='codecov-') as tmpdir:
-        codecov_bin = pathlib.Path(tmpdir) / 'codecov'
+    url = "https://ansible-ci-files.s3.amazonaws.com/codecov/linux/codecov"
+    with tempfile.TemporaryDirectory(prefix="codecov-") as tmpdir:
+        codecov_bin = pathlib.Path(tmpdir) / "codecov"
         download_file(url, codecov_bin, 0o755, args.dry_run)
 
         files = process_files(args.path)
         upload_files(codecov_bin, files, args.dry_run)
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     main()

.azure-pipelines/scripts/time-command.py

@@ -5,8 +5,7 @@
 
 """Prepends a relative timestamp to each input line from stdin and writes it to stdout."""
 
-from __future__ import (absolute_import, division, print_function)
-__metaclass__ = type
+from __future__ import annotations
 
 import sys
 import time
@@ -16,14 +15,14 @@ def main():
     """Main program entry point."""
     start = time.time()
 
-    sys.stdin.reconfigure(errors='surrogateescape')
-    sys.stdout.reconfigure(errors='surrogateescape')
+    sys.stdin.reconfigure(errors="surrogateescape")
+    sys.stdout.reconfigure(errors="surrogateescape")
 
     for line in sys.stdin:
         seconds = time.time() - start
-        sys.stdout.write('%02d:%02d %s' % (seconds // 60, seconds % 60, line))
+        sys.stdout.write("%02d:%02d %s" % (seconds // 60, seconds % 60, line))
         sys.stdout.flush()
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     main()

.devcontainer/devcontainer.json

@@ -0,0 +1,34 @@
+{
+  "name": "community.general devcontainer",
+  "image": "mcr.microsoft.com/devcontainers/python:3.14-bookworm",
+  "features": {
+    "ghcr.io/devcontainers/features/docker-in-docker:2": {}
+  },
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "terminal.integrated.shell.linux": "/bin/bash",
+        "python.pythonPath": "/usr/local/bin/python",
+        "editor.defaultFormatter": "charliermarsh.ruff",
+        "editor.formatOnSave": true,
+        "files.autoSave": "afterDelay",
+        "files.eol": "\n",
+        "files.insertFinalNewline": true,
+        "files.trimFinalNewlines": true,
+        "files.trimTrailingWhitespace": true
+      },
+      "extensions": [
+        "charliermarsh.ruff",
+        "ms-python.python",
+        "ms-python.vscode-pylance",
+        "redhat.ansible",
+        "redhat.vscode-yaml",
+        "trond-snekvik.simple-rst",
+      ]
+    }
+  },
+  "remoteUser": "vscode",
+  "postCreateCommand": ".devcontainer/setup.sh",
+  "workspaceFolder": "/workspace/ansible_collections/community/general",
+  "workspaceMount": "source=${localWorkspaceFolder},target=/workspace/ansible_collections/community/general,type=bind"
+}

.devcontainer/devcontainer.json.license

@@ -0,0 +1,3 @@
+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
+SPDX-FileCopyrightText: 2025 Alexei Znamensky <russoz@gmail.com>

.devcontainer/requirements-dev.txt

@@ -1,7 +1,10 @@
-# Copyright (c) 2023, Sergei Antipov <greendayonfire at gmail.com>
 # 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
+# SPDX-FileCopyrightText: 2025 Alexei Znamensky <russoz@gmail.com>
 
-poolid: test
-member: local
-member_type: storage
+nox
+ruff
+antsibull-nox
+pre-commit
+ansible-core
+andebox

.devcontainer/setup.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# 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
+
+sudo chown -R vscode:vscode /workspace/
+
+pip install -U pip
+pip install -r .devcontainer/requirements-dev.txt
+pip install -r tests/unit/requirements.txt
+
+export ANSIBLE_COLLECTIONS_PATH=/workspace:${ANSIBLE_COLLECTIONS_PATH}
+ansible-galaxy collection install -v -r tests/unit/requirements.yml
+ansible-galaxy collection install -v -r tests/integration/requirements.yml
+
+pre-commit install

.git-blame-ignore-revs

@@ -3,7 +3,11 @@
 # SPDX-License-Identifier: GPL-3.0-or-later
 
 # YAML reformatting
-2b4882549908b5b1fafe5fa10efb47f613a71f94
-8196cacff8e83dc5d7fb88b43ef3cab5d3751c39
-bd4f1a3e5ca1af5afc53636c36767e81a4566978
-a9e892952deef6f91977d7032dd95237a9867509
+d032de3b16eed11ea3a31cd3d96d78f7c46a2ee0
+e8f965fbf8154ea177c6622da149f2ae8533bd3c
+e938ca5f20651abc160ee6aba10014013d04dcc1
+eaa5e07b2866e05b6c7b5628ca92e9cb1142d008
+
+# Code reformatting
+340ff8586d4f1cb6a0f3c934eb42589bcc29c0ea
+e530d2906a1f61df89861286ac57c951a247f32c

.github/BOTMETA.yml

@@ -92,12 +92,13 @@ files:
     maintainers: ryancurrah
   $callbacks/syslog_json.py:
     maintainers: imjoseangel
+  $callbacks/tasks_only.py:
+    maintainers: felixfontein
   $callbacks/timestamp.py:
     maintainers: kurokobo
   $callbacks/unixy.py:
     labels: unixy
     maintainers: akatch
-  $callbacks/yaml.py: {}
   $connections/:
     labels: connections
   $connections/chroot.py: {}
@@ -113,9 +114,6 @@ files:
   $connections/lxd.py:
     labels: lxd
     maintainers: mattclay
-  $connections/proxmox_pct_remote.py:
-    labels: proxmox
-    maintainers: mietzen
   $connections/qubes.py:
     maintainers: kushaldas
   $connections/saltstack.py:
@@ -127,8 +125,6 @@ files:
     maintainers: $team_ansible_core
   $doc_fragments/:
     labels: docs_fragments
-  $doc_fragments/clc.py:
-    maintainers: clc-runner russoz
   $doc_fragments/django.py:
     maintainers: russoz
   $doc_fragments/hpe3par.py:
@@ -212,6 +208,8 @@ files:
     maintainers: resmo
   $filters/to_months.yml:
     maintainers: resmo
+  $filters/to_nice_yaml.yml:
+    maintainers: felixfontein
   $filters/to_prettytable.py:
     maintainers: tgadiev
   $filters/to_seconds.yml:
@@ -220,6 +218,10 @@ files:
     maintainers: resmo
   $filters/to_weeks.yml:
     maintainers: resmo
+  $filters/to_yaml.py:
+    maintainers: felixfontein
+  $filters/to_yaml.yml:
+    maintainers: felixfontein
   $filters/to_years.yml:
     maintainers: resmo
   $filters/unicode_normalize.py:
@@ -236,6 +238,9 @@ files:
     maintainers: vbotka
   $inventories/icinga2.py:
     maintainers: BongoEADGC6
+  $inventories/incus.py:
+    labels: incus
+    maintainers: stgraber
   $inventories/linode.py:
     keywords: linode dynamic inventory script
     labels: cloud linode
@@ -249,18 +254,16 @@ files:
     keywords: opennebula dynamic inventory script
     labels: cloud opennebula
     maintainers: feldsam
-  $inventories/proxmox.py:
-    maintainers: $team_virt ilijamt krauthosting
   $inventories/scaleway.py:
     labels: cloud scaleway
     maintainers: $team_scaleway
-  $inventories/stackpath_compute.py:
-    maintainers: shayrybak
   $inventories/virtualbox.py: {}
   $inventories/xen_orchestra.py:
     maintainers: ddelnano shinuza
   $lookups/:
     labels: lookups
+  $lookups/binary_file.py:
+    maintainers: felixfontein
   $lookups/bitwarden_secrets_manager.py:
     maintainers: jantari
   $lookups/bitwarden.py:
@@ -292,16 +295,13 @@ files:
     maintainers: dagwieers
   $lookups/flattened.py: {}
   $lookups/github_app_access_token.py:
-    maintainers: weisheng-p
+    maintainers: weisheng-p blavoie
   $lookups/hiera.py:
     maintainers: jparrill
   $lookups/keyring.py: {}
   $lookups/lastpass.py: {}
   $lookups/lmdb_kv.py:
     maintainers: jpmens
-  $lookups/manifold.py:
-    labels: manifold
-    maintainers: galanoff
   $lookups/merge_variables.py:
     maintainers: rlenferink m-a-r-k-e alpex8
   $lookups/onepass:
@@ -368,6 +368,8 @@ files:
   $module_utils/jenkins.py:
     labels: jenkins
     maintainers: russoz
+  $module_utils/_lxc.py:
+    maintainers: russoz
   $module_utils/manageiq.py:
     labels: manageiq
     maintainers: $team_manageiq
@@ -396,9 +398,6 @@ files:
   $module_utils/puppet.py:
     labels: puppet
     maintainers: russoz
-  $module_utils/pure.py:
-    labels: pure pure_storage
-    maintainers: $team_purestorage
   $module_utils/redfish_utils.py:
     labels: redfish_utils
     maintainers: $team_redfish
@@ -482,8 +481,6 @@ files:
     keywords: beadm dladm illumos ipadm nexenta omnios openindiana pfexec smartos solaris sunos zfs zpool
     labels: beadm solaris
     maintainers: $team_solaris
-  $modules/bearychat.py:
-    maintainers: tonyseek
   $modules/bigpanda.py:
     ignore: hkariti
   $modules/bitbucket_:
@@ -510,8 +507,6 @@ files:
     maintainers: NickatEpic
   $modules/cisco_webex.py:
     maintainers: drew-russell
-  $modules/clc_:
-    maintainers: clc-runner
   $modules/cloud_init_data_facts.py:
     maintainers: resmo
   $modules/cloudflare_dns.py:
@@ -560,6 +555,10 @@ files:
     maintainers: russoz
   $modules/django_createcachetable.py:
     maintainers: russoz
+  $modules/django_dumpdata.py:
+    maintainers: russoz
+  $modules/django_loaddata.py:
+    maintainers: russoz
   $modules/django_manage.py:
     ignore: scottanderson42 tastychutney
     labels: django_manage
@@ -587,9 +586,6 @@ files:
   $modules/etcd3.py:
     ignore: vfauth
     maintainers: evrardjp
-  $modules/facter.py:
-    labels: facter
-    maintainers: $team_ansible_core gamethis
   $modules/facter_facts.py:
     labels: facter
     maintainers: russoz $team_ansible_core gamethis
@@ -598,6 +594,8 @@ files:
   $modules/filesystem.py:
     labels: filesystem
     maintainers: pilou- abulimov quidame
+  $modules/file_remove.py:
+    maintainers: shahargolshani
   $modules/flatpak.py:
     maintainers: $team_flatpak
   $modules/flatpak_remote.py:
@@ -670,8 +668,6 @@ files:
     maintainers: marns93
   $modules/hg.py:
     maintainers: yeukhon
-  $modules/hipchat.py:
-    maintainers: pb8226 shirou
   $modules/homebrew.py:
     ignore: ryansb
     keywords: brew cask darwin homebrew macosx macports osx
@@ -751,6 +747,8 @@ files:
     maintainers: obourdon hryamzik
   $modules/ip_netns.py:
     maintainers: bregman-arie
+  $modules/ip2location_info.py:
+    maintainers: ip2location
   $modules/ipa_:
     maintainers: $team_ipa
     ignore: fxfitz
@@ -797,6 +795,8 @@ files:
     maintainers: brettmilford unnecessary-username juanmcasanova
   $modules/jenkins_build_info.py:
     maintainers: juanmcasanova
+  $modules/jenkins_credential.py:
+    maintainers: YoussefKhalidAli
   $modules/jenkins_job.py:
     maintainers: sermilrod
   $modules/jenkins_job_info.py:
@@ -813,6 +813,8 @@ files:
     maintainers: Slezhuk pertoft
   $modules/kdeconfig.py:
     maintainers: smeso
+  $modules/kea_command.py:
+    maintainers: mirabilos
   $modules/kernel_blacklist.py:
     maintainers: matze
   $modules/keycloak_:
@@ -867,6 +869,8 @@ files:
     maintainers: bratwurzt
   $modules/keycloak_realm_rolemapping.py:
     maintainers: agross mhuysamen Gaetan2907
+  $modules/keycloak_user_execute_actions_email.py:
+    maintainers: mariusbertram
   $modules/keyring.py:
     maintainers: ahussey-redhat
   $modules/keyring_info.py:
@@ -913,6 +917,10 @@ files:
     maintainers: nerzhul
   $modules/lvg.py:
     maintainers: abulimov
+  $modules/lvm_pv.py:
+    maintainers: klention
+  $modules/lvm_pv_move_data.py:
+    maintainers: klention
   $modules/lvg_rename.py:
     maintainers: lszomor
   $modules/lvol.py:
@@ -927,6 +935,10 @@ files:
     maintainers: conloos
   $modules/lxd_project.py:
     maintainers: we10710aa
+  $modules/lxd_storage_pool_info.py:
+    maintainers: smcavoy
+  $modules/lxd_storage_volume_info.py:
+    maintainers: smcavoy
   $modules/macports.py:
     ignore: ryansb
     keywords: brew cask darwin homebrew macosx macports osx
@@ -1067,9 +1079,13 @@ files:
   $modules/ovh_monthly_billing.py:
     maintainers: fraff
   $modules/pacemaker_cluster.py:
-    maintainers: matbu
+    maintainers: matbu munchtoast
+  $modules/pacemaker_info.py:
+    maintainers: munchtoast
   $modules/pacemaker_resource.py:
     maintainers: munchtoast
+  $modules/pacemaker_stonith.py:
+    maintainers: munchtoast
   $modules/packet_:
     maintainers: nurfet-becirevic t0mk
   $modules/packet_device.py:
@@ -1145,36 +1161,6 @@ files:
     maintainers: $team_bsd berenddeboer
   $modules/pritunl_:
     maintainers: Lowess
-  $modules/profitbricks:
-    maintainers: baldwinSPC
-  $modules/proxmox:
-    keywords: kvm libvirt proxmox qemu
-    labels: proxmox virt
-    maintainers: $team_virt UnderGreen krauthosting
-    ignore: tleguern
-  $modules/proxmox.py:
-    ignore: skvidal
-    maintainers: UnderGreen krauthosting
-  $modules/proxmox_disk.py:
-    maintainers: castorsky krauthosting
-  $modules/proxmox_kvm.py:
-    ignore: skvidal
-    maintainers: helldorado krauthosting
-  $modules/proxmox_backup.py:
-    maintainers: IamLunchbox
-  $modules/proxmox_backup_info.py:
-    maintainers: raoufnezhad mmayabi
-  $modules/proxmox_nic.py:
-    maintainers: Kogelvis krauthosting
-  $modules/proxmox_node_info.py:
-    maintainers: jwbernin krauthosting
-  $modules/proxmox_storage_contents_info.py:
-    maintainers: l00ptr krauthosting
-  $modules/proxmox_tasks_info:
-    maintainers: paginabianca krauthosting
-  $modules/proxmox_template.py:
-    ignore: skvidal
-    maintainers: UnderGreen krauthosting
   $modules/pubnub_blocks.py:
     maintainers: parfeon pubnub
   $modules/pulp_repo.py:
@@ -1489,6 +1475,8 @@ files:
     maintainers: natefoo
   $modules/znode.py:
     maintainers: treyperry
+  $modules/zpool.py:
+    maintainers: tomhesse
   $modules/zpool_facts:
     keywords: beadm dladm illumos ipadm nexenta omnios openindiana pfexec smartos solaris sunos zfs zpool
     labels: solaris
@@ -1516,7 +1504,9 @@ files:
     maintainers: vbotka
   $tests/fqdn_valid.py:
     maintainers: vbotka
-#########################
+  $modules/sssd_info.py:
+    maintainers: a-gabidullin
+  #########################
   docs/docsite/rst/filter_guide.rst: {}
   docs/docsite/rst/filter_guide_abstract_informations.rst: {}
   docs/docsite/rst/filter_guide_abstract_informations_counting_elements_in_sequence.rst:
@@ -1555,6 +1545,22 @@ files:
     maintainers: russoz
   docs/docsite/rst/guide_deps.rst:
     maintainers: russoz
+  docs/docsite/rst/guide_iocage.rst:
+    maintainers: russoz felixfontein
+  docs/docsite/rst/guide_iocage_inventory.rst:
+    maintainers: vbotka
+  docs/docsite/rst/guide_iocage_inventory_aliases.rst:
+    maintainers: vbotka
+  docs/docsite/rst/guide_iocage_inventory_basics.rst:
+    maintainers: vbotka
+  docs/docsite/rst/guide_iocage_inventory_dhcp.rst:
+    maintainers: vbotka
+  docs/docsite/rst/guide_iocage_inventory_hooks.rst:
+    maintainers: vbotka
+  docs/docsite/rst/guide_iocage_inventory_properties.rst:
+    maintainers: vbotka
+  docs/docsite/rst/guide_iocage_inventory_tags.rst:
+    maintainers: vbotka
   docs/docsite/rst/guide_modulehelper.rst:
     maintainers: russoz
   docs/docsite/rst/guide_online.rst:
@@ -1569,7 +1575,7 @@ files:
     maintainers: russoz
   docs/docsite/rst/test_guide.rst:
     maintainers: felixfontein
-#########################
+  #########################
   tests/:
     labels: tests
   tests/integration:
@@ -1596,7 +1602,7 @@ macros:
   plugin_utils: plugins/plugin_utils
   tests: plugins/test
   team_ansible_core:
-  team_aix: MorrisA bcoca d-little flynn1973 gforster kairoaraujo marvin-sinister molekuul ramooncamacho wtcross
+  team_aix: MorrisA bcoca d-little flynn1973 gforster kairoaraujo marvin-sinister mator molekuul ramooncamacho wtcross
   team_bsd: JoergFiedler MacLemon bcoca dch jasperla mekanix opoplawski overhacked tuxillo
   team_consul: sgargan apollo13 Ilgmi
   team_cyberark_conjur: jvanderhoof ryanprior
@@ -1614,11 +1620,10 @@ macros:
   team_networking: NilashishC Qalthos danielmellado ganeshrn justjais trishnaguha sganesh-infoblox privateip
   team_opennebula: ilicmilan meerkampdvv rsmontero xorel nilsding
   team_oracle: manojmeda mross22 nalsaber
-  team_purestorage: bannaych dnix101 genegr lionmax opslounge raekins sdodsley sile16
   team_redfish: mraineri tomasg2012 xmadsen renxulei rajeevkallur bhavya06 jyundt
   team_rhsm: cnsnyder ptoscano
   team_scaleway: remyleone abarbare
-  team_solaris: bcoca fishman jasperla jpdasma scathatheworm troy2914 xen0l
+  team_solaris: bcoca fishman jasperla jpdasma mator scathatheworm troy2914 xen0l
   team_suse: commel evrardjp lrupp AnderEnder alxgu andytom sealor
   team_virt: joshainglis karmab Thulium-Drake Ajpantuso
   team_wdc: mikemoerk

.github/dependabot.yml

@@ -9,3 +9,7 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
+    groups:
+      ci:
+        patterns:
+          - "*"

.github/workflows/ansible-test.yml

@@ -29,14 +29,7 @@ jobs:
     strategy:
       matrix:
         ansible:
-          - '2.15'
-          - '2.16'
           - '2.17'
-    # Ansible-test on various stable branches does not yet work well with cgroups v2.
-    # Since ubuntu-latest now uses Ubuntu 22.04, we need to fall back to the ubuntu-20.04
-    # image for these stable branches. The list of branches where this is necessary will
-    # shrink over time, check out https://github.com/ansible-collections/news-for-maintainers/issues/28
-    # for the latest list.
     runs-on: ubuntu-latest
     steps:
       - name: Perform sanity testing
@@ -51,11 +44,6 @@ jobs:
             git clone --depth=1 --single-branch https://github.com/ansible-collections/community.internal_test_tools.git ../../community/internal_test_tools
 
   units:
-    # Ansible-test on various stable branches does not yet work well with cgroups v2.
-    # Since ubuntu-latest now uses Ubuntu 22.04, we need to fall back to the ubuntu-20.04
-    # image for these stable branches. The list of branches where this is necessary will
-    # shrink over time, check out https://github.com/ansible-collections/news-for-maintainers/issues/28
-    # for the latest list.
     runs-on: ubuntu-latest
     name: EOL Units (Ⓐ${{ matrix.ansible }}+py${{ matrix.python }})
     strategy:
@@ -69,18 +57,6 @@ jobs:
         exclude:
           - ansible: ''
         include:
-          - ansible: '2.15'
-            python: '2.7'
-          - ansible: '2.15'
-            python: '3.5'
-          - ansible: '2.15'
-            python: '3.10'
-          - ansible: '2.16'
-            python: '2.7'
-          - ansible: '2.16'
-            python: '3.6'
-          - ansible: '2.16'
-            python: '3.11'
           - ansible: '2.17'
             python: '3.7'
           - ansible: '2.17'
@@ -106,11 +82,6 @@ jobs:
           testing-type: units
 
   integration:
-    # Ansible-test on various stable branches does not yet work well with cgroups v2.
-    # Since ubuntu-latest now uses Ubuntu 22.04, we need to fall back to the ubuntu-20.04
-    # image for these stable branches. The list of branches where this is necessary will
-    # shrink over time, check out https://github.com/ansible-collections/news-for-maintainers/issues/28
-    # for the latest list.
     runs-on: ubuntu-latest
     name: EOL I (Ⓐ${{ matrix.ansible }}+${{ matrix.docker }}+py${{ matrix.python }}:${{ matrix.target }})
     strategy:
@@ -127,68 +98,6 @@ jobs:
         exclude:
           - ansible: ''
         include:
-          # 2.15
-          - ansible: '2.15'
-            docker: alpine3
-            python: ''
-            target: azp/posix/1/
-          - ansible: '2.15'
-            docker: alpine3
-            python: ''
-            target: azp/posix/2/
-          - ansible: '2.15'
-            docker: alpine3
-            python: ''
-            target: azp/posix/3/
-          - ansible: '2.15'
-            docker: fedora37
-            python: ''
-            target: azp/posix/1/
-          - ansible: '2.15'
-            docker: fedora37
-            python: ''
-            target: azp/posix/2/
-          - ansible: '2.15'
-            docker: fedora37
-            python: ''
-            target: azp/posix/3/
-          # 2.16
-          - ansible: '2.16'
-            docker: alpine3
-            python: ''
-            target: azp/posix/1/
-          - ansible: '2.16'
-            docker: alpine3
-            python: ''
-            target: azp/posix/2/
-          - ansible: '2.16'
-            docker: alpine3
-            python: ''
-            target: azp/posix/3/
-          - ansible: '2.16'
-            docker: fedora38
-            python: ''
-            target: azp/posix/1/
-          - ansible: '2.16'
-            docker: fedora38
-            python: ''
-            target: azp/posix/2/
-          - ansible: '2.16'
-            docker: fedora38
-            python: ''
-            target: azp/posix/3/
-          - ansible: '2.16'
-            docker: opensuse15
-            python: ''
-            target: azp/posix/1/
-          - ansible: '2.16'
-            docker: opensuse15
-            python: ''
-            target: azp/posix/2/
-          - ansible: '2.16'
-            docker: opensuse15
-            python: ''
-            target: azp/posix/3/
           # 2.17
           - ansible: '2.17'
             docker: fedora39
@@ -202,18 +111,6 @@ jobs:
             docker: fedora39
             python: ''
             target: azp/posix/3/
-          - ansible: '2.17'
-            docker: alpine319
-            python: ''
-            target: azp/posix/1/
-          - ansible: '2.17'
-            docker: alpine319
-            python: ''
-            target: azp/posix/2/
-          - ansible: '2.17'
-            docker: alpine319
-            python: ''
-            target: azp/posix/3/
           - ansible: '2.17'
             docker: ubuntu2004
             python: ''
@@ -226,6 +123,27 @@ jobs:
             docker: ubuntu2004
             python: ''
             target: azp/posix/3/
+          - ansible: '2.17'
+            docker: alpine319
+            python: ''
+            target: azp/posix/1/
+          - ansible: '2.17'
+            docker: alpine319
+            python: ''
+            target: azp/posix/2/
+          - ansible: '2.17'
+            docker: alpine319
+            python: ''
+            target: azp/posix/3/
+          # Right now all generic tests are disabled. Uncomment when at least one of them is re-enabled.
+          # - ansible: '2.17'
+          #   docker: default
+          #   python: '3.7'
+          #   target: azp/generic/1/
+          # - ansible: '2.17'
+          #   docker: default
+          #   python: '3.12'
+          #   target: azp/generic/1/
 
     steps:
       - name: >-

.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@v6
+        with:
+          persist-credentials: false
+      - name: Run nox
+        uses: ansible-community/antsibull-nox@main
+        with:
+          sessions: ansible-output

.gitignore

@@ -530,3 +530,4 @@ tests/integration/cloud-config-*.ini
 
 # VSCode specific extensions
 .vscode/settings.json
+.ansible

.mypy.ini

@@ -0,0 +1,216 @@
+# 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
+
+[mypy]
+# check_untyped_defs = True
+# disallow_untyped_defs = True
+
+# strict = True -- only try to enable once everything (including dependencies!) is typed
+strict_equality = True
+strict_bytes = True
+
+warn_redundant_casts = True
+# warn_return_any = True
+warn_unreachable = True
+
+[mypy-ansible.*]
+# ansible-core has partial typing information
+follow_untyped_imports = True
+
+# The following imports are Python packages that:
+# 1. We do not install (we can't install everything!);
+# 2. That have type stubs, but we don't install them (again, we can't install everything!); or
+# 3. That have no types and type stubs.
+[mypy-aerospike.*]
+ignore_missing_imports = True
+[mypy-boto3.*]
+ignore_missing_imports = True
+[mypy-bs4.*]
+ignore_missing_imports = True
+[mypy-cgi.*]
+ignore_missing_imports = True
+[mypy-chef.*]
+ignore_missing_imports = True
+[mypy-consul.*]
+ignore_missing_imports = True
+[mypy-credstash.*]
+ignore_missing_imports = True
+[mypy-crypt.*]
+ignore_missing_imports = True
+[mypy-datadog.*]
+ignore_missing_imports = True
+[mypy-dbus.*]
+ignore_missing_imports = True
+[mypy-delinea.*]
+ignore_missing_imports = True
+[mypy-dnf.*]
+ignore_missing_imports = True
+[mypy-dnsimple.*]
+ignore_missing_imports = True
+[mypy-etcd3.*]
+ignore_missing_imports = True
+[mypy-flatdict.*]
+ignore_missing_imports = True
+[mypy-footmark.*]
+ignore_missing_imports = True
+[mypy-fqdn.*]
+ignore_missing_imports = True
+[mypy-func.*]
+ignore_missing_imports = True
+[mypy-gi.*]
+ignore_missing_imports = True
+[mypy-github3.*]
+ignore_missing_imports = True
+[mypy-hashids.*]
+ignore_missing_imports = True
+[mypy-heroku3.*]
+ignore_missing_imports = True
+[mypy-hpe3parclient.*]
+ignore_missing_imports = True
+[mypy-hpe3par_sdk.*]
+ignore_missing_imports = True
+[mypy-hpilo.*]
+ignore_missing_imports = True
+[mypy-hpOneView.*]
+ignore_missing_imports = True
+[mypy-httmock.*]  # TODO!
+ignore_missing_imports = True
+[mypy-influxdb.*]
+ignore_missing_imports = True
+[mypy-jc.*]
+ignore_missing_imports = True
+[mypy-jenkins.*]
+ignore_missing_imports = True
+[mypy-jmespath.*]
+ignore_missing_imports = True
+[mypy-jsonpatch.*]
+ignore_missing_imports = True
+[mypy-kazoo.*]
+ignore_missing_imports = True
+[mypy-keyring.*]
+ignore_missing_imports = True
+[mypy-keystoneauth1.*]
+ignore_missing_imports = True
+[mypy-layman.*]
+ignore_missing_imports = True
+[mypy-ldap.*]
+ignore_missing_imports = True
+[mypy-legacycrypt.*]
+ignore_missing_imports = True
+[mypy-libcloud.*]
+ignore_missing_imports = True
+[mypy-linode.*]
+ignore_missing_imports = True
+[mypy-linode_api4.*]
+ignore_missing_imports = True
+[mypy-lmdb.*]
+ignore_missing_imports = True
+[mypy-logdna.*]
+ignore_missing_imports = True
+[mypy-logstash.*]
+ignore_missing_imports = True
+[mypy-lxc.*]
+ignore_missing_imports = True
+[mypy-manageiq_client.*]
+ignore_missing_imports = True
+[mypy-matrix_client.*]
+ignore_missing_imports = True
+[mypy-memcache.*]
+ignore_missing_imports = True
+[mypy-nc_dnsapi.*]
+ignore_missing_imports = True
+[mypy-nomad.*]
+ignore_missing_imports = True
+[mypy-oci.*]
+ignore_missing_imports = True
+[mypy-oneandone.*]
+ignore_missing_imports = True
+[mypy-opentelemetry.*]
+ignore_missing_imports = True
+[mypy-ovh.*]
+ignore_missing_imports = True
+[mypy-ovirtsdk.*]
+ignore_missing_imports = True
+[mypy-packet.*]
+ignore_missing_imports = True
+[mypy-paho.*]
+ignore_missing_imports = True
+[mypy-pam.*]
+ignore_missing_imports = True
+[mypy-pdpyras.*]
+ignore_missing_imports = True
+[mypy-petname.*]
+ignore_missing_imports = True
+[mypy-pingdom.*]
+ignore_missing_imports = True
+[mypy-portage.*]
+ignore_missing_imports = True
+[mypy-potatoes_that_will_never_be_there.*]
+ignore_missing_imports = True
+[mypy-prettytable.*]
+ignore_missing_imports = True
+[mypy-pubnub_blocks_client.*]
+ignore_missing_imports = True
+[mypy-pushbullet.*]
+ignore_missing_imports = True
+[mypy-pycdlib.*]
+ignore_missing_imports = True
+[mypy-pyghmi.*]
+ignore_missing_imports = True
+[mypy-pylxca.*]
+ignore_missing_imports = True
+[mypy-pymssql.*]
+ignore_missing_imports = True
+[mypy-pyodbc.*]
+ignore_missing_imports = True
+[mypy-pyone.*]
+ignore_missing_imports = True
+[mypy-pypureomapi.*]
+ignore_missing_imports = True
+[mypy-pysnmp.*]
+ignore_missing_imports = True
+[mypy-pyxcli.*]
+ignore_missing_imports = True
+[mypy-rpm.*]
+ignore_missing_imports = True
+[mypy-salt.*]
+ignore_missing_imports = True
+[mypy-selinux.*]
+ignore_missing_imports = True
+[mypy-semantic_version.*]
+ignore_missing_imports = True
+[mypy-sendgrid.*]
+ignore_missing_imports = True
+[mypy-seobject.*]
+ignore_missing_imports = True
+[mypy-sha.*]
+ignore_missing_imports = True
+[mypy-SoftLayer.*]
+ignore_missing_imports = True
+[mypy-spotinst_sdk.*]
+ignore_missing_imports = True
+[mypy-statsd.*]
+ignore_missing_imports = True
+[mypy-storops.*]
+ignore_missing_imports = True
+[mypy-taiga.*]
+ignore_missing_imports = True
+[mypy-thycotic.*]
+ignore_missing_imports = True
+[mypy-univention.*]
+ignore_missing_imports = True
+[mypy-vexatapi.*]
+ignore_missing_imports = True
+[mypy-websocket.*]
+ignore_missing_imports = True
+[mypy-XenAPI.*]
+ignore_missing_imports = True
+[mypy-xkcdpass.*]
+ignore_missing_imports = True
+[mypy-xmljson.*]
+ignore_missing_imports = True
+[mypy-xmltodict.*]
+ignore_missing_imports = True
+[mypy-xmpp.*]
+ignore_missing_imports = True

.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+# 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
+# SPDX-FileCopyrightText: 2025 Alexei Znamensky <russoz@gmail.com>
+
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.14.10
+    hooks:
+      # Run the linter.
+      - id: ruff-check
+      # Run the formatter.
+      - id: ruff-format

.yamllint

@@ -0,0 +1,52 @@
+---
+# 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
+
+extends: default
+
+ignore: |
+  /changelogs/
+
+rules:
+  line-length:
+    max: 1000
+    level: error
+  document-start: disable
+  document-end: disable
+  truthy:
+    level: error
+    allowed-values:
+      - 'true'
+      - 'false'
+  indentation:
+    spaces: 2
+    indent-sequences: true
+  key-duplicates: enable
+  trailing-spaces: enable
+  new-line-at-end-of-file: disable
+  hyphens:
+    max-spaces-after: 1
+  empty-lines:
+    max: 2
+    max-start: 0
+    max-end: 0
+  commas:
+    max-spaces-before: 0
+    min-spaces-after: 1
+    max-spaces-after: 1
+  colons:
+    max-spaces-before: 0
+    max-spaces-after: 1
+  brackets:
+    min-spaces-inside: 0
+    max-spaces-inside: 0
+  braces:
+    min-spaces-inside: 0
+    max-spaces-inside: 1
+  octal-values:
+    forbid-implicit-octal: true
+    forbid-explicit-octal: true
+  comments:
+    min-spaces-from-content: 1
+  comments-indentation: false

CONTRIBUTING.md

@@ -39,7 +39,7 @@ Please read our ['Contributing to collections'](https://docs.ansible.com/project
 * Make sure your PR includes a [changelog fragment](https://docs.ansible.com/projects/ansible/devel/community/collection_development_process.html#creating-a-changelog-fragment).
   * You must not include a fragment for new modules or new plugins. Also you shouldn't include one for docs-only changes. (If you're not sure, simply don't include one, we'll tell you whether one is needed or not :) )
   * Please always include a link to the pull request itself, and if the PR is about an issue, also a link to the issue. Also make sure the fragment ends with a period, and begins with a lower-case letter after `-`. (Again, if you don't do this, we'll add suggestions to fix it, so don't worry too much :) )
-* Avoid reformatting unrelated parts of the codebase in your PR. These types of changes will likely be requested for reversion, create additional work for reviewers, and may cause approval to be delayed.
+* Note that we format the code with `ruff format`. If your change does not match the formatters expectations, CI will fail and your PR will not get merged. See below for how to format code with antsibull-nox.
 
 You can also read the Ansible community's [Quick-start development guide](https://docs.ansible.com/projects/ansible/devel/community/create_pr_quick_start.html).
 
@@ -49,11 +49,24 @@ If you want to test a PR locally, refer to [our testing guide](https://docs.ansi
 
 If you find any inconsistencies or places in this document which can be improved, feel free to raise an issue or pull request to fix it.
 
-## Run sanity or unit locally (with antsibull-nox)
+## Format code; and run sanity or unit tests locally (with antsibull-nox)
 
-The easiest way to run sanity and unit tests locally is to use [antsibull-nox](https://docs.ansible.com/projects/antsibull-nox/).
+The easiest way to format the code, and to run sanity and unit tests locally is to use [antsibull-nox](https://docs.ansible.com/projects/antsibull-nox/).
 (If you have [nox](https://nox.thea.codes/en/stable/) installed, it will automatically install antsibull-nox in a virtual environment for you.)
 
+### Format code
+
+The following commands show how to run ansible-test sanity tests:
+
+```.bash
+# Run all configured formatters:
+nox -Re formatters
+
+# If you notice discrepancies between your local formatter and CI, you might
+# need to re-generate the virtual environment:
+nox -e formatters
+```
+
 ### Sanity tests
 
 The following commands show how to run ansible-test sanity tests:
@@ -120,6 +133,7 @@ ansible-test sanity --docker -v plugins/modules/system/pids.py tests/integration
 Note that for running unit tests, you need to install required collections in the same folder structure that `community.general` is checked out in.
 Right now, you need to install [`community.internal_test_tools`](https://github.com/ansible-collections/community.internal_test_tools).
 If you want to use the latest version from GitHub, you can run:
+
 ```
 git clone https://github.com/ansible-collections/community.internal_test_tools.git ~/dev/ansible_collections/community/internal_test_tools
 ```
@@ -142,6 +156,7 @@ ansible-test units --docker -v --python 3.8 tests/unit/plugins/modules/net_tools
 Note that for running integration tests, you need to install required collections in the same folder structure that `community.general` is checked out in.
 Right now, depending on the test, you need to install [`ansible.posix`](https://github.com/ansible-collections/ansible.posix), [`community.crypto`](https://github.com/ansible-collections/community.crypto), and [`community.docker`](https://github.com/ansible-collections/community.docker):
 If you want to use the latest versions from GitHub, you can run:
+
 ```
 mkdir -p ~/dev/ansible_collections/ansible
 git clone https://github.com/ansible-collections/ansible.posix.git ~/dev/ansible_collections/ansible/posix
@@ -154,11 +169,13 @@ The following commands show how to run integration tests:
 #### In Docker
 
 Integration tests on Docker have the following parameters:
+
 - `image_name` (required): The name of the Docker image. To get the list of supported Docker images, run
   `ansible-test integration --help` and look for _target docker images_.
 - `test_name` (optional): The name of the integration test.
   For modules, this equals the short name of the module; for example, `pacman` in case of `community.general.pacman`.
   For plugins, the plugin type is added before the plugin's short name, for example `callback_yaml` for the `community.general.yaml` callback.
+
 ```.bash
 # Test all plugins/modules on fedora40
 ansible-test integration -v --docker fedora40
@@ -179,6 +196,31 @@ ansible-test integration -v lookup_flattened
 
 If you are unsure about the integration test target name for a module or plugin, you can take a look in `tests/integration/targets/`. Tests for plugins have the plugin type prepended.
 
+## Devcontainer
+
+Since community.general 12.2.0, the project repository supports [devcontainers](https://containers.dev/). In short, it is a standard mechanism to
+create a container that is then used during the development cycle. Many tools are pre-installed in the container and will be already available
+to you as a developer. A number of different IDEs support that configuration, the most prominent ones being VSCode and PyCharm.
+
+See the files under [.devcontainer](.devcontainer) for details on what is deployed inside that container.
+
+Beware of:
+
+- By default, the devcontainer installs the latest version of `ansible-core`.
+  When testing your changes locally, keep in mind that the collection must support older versions of
+  `ansible-core` and, depending on what is being tested, results may vary.
+- Integration tests executed directly inside the devcontainer without isolation (see above) may fail if
+  they expected to be run in full fledged VMs. On the other hand, the devcontainer setup allows running
+  containers inside the container (the `docker-in-docker` feature).
+- The devcontainer is built with a directory structure such that
+  `.../ansible_collections/community/general` contains the project repository, so `ansible-test` and
+  other standard tools should work without any additional setup
+- By default, the devcontainer installs `pre-commit` and configures it to perform `ruff check` and
+  `ruff format` on the Python files, prior to commiting. That configuration is going to be used by
+  `git` even outside the devcontainer. To prevent errors, you have to either install `pre-commit` in
+  your computer, outside the devcontainer, or run `pre-commit uninstall` from within the devcontainer
+  before quitting it.
+
 ## Creating new modules or plugins
 
 Creating new modules and plugins requires a bit more work than other Pull Requests.
@@ -188,7 +230,7 @@ Creating new modules and plugins requires a bit more work than other Pull Reques
 
 2. Please do not add more than one plugin/module in one PR, especially if it is the first plugin/module you are contributing.
    That makes it easier for reviewers, and increases the chance that your PR will get merged. If you plan to contribute a group
-   of plugins/modules (say, more than a module and a corresponding ``_info`` module), please mention that in the first PR. In
+   of plugins/modules (say, more than a module and a corresponding `_info` module), please mention that in the first PR. In
    such cases, you also have to think whether it is better to publish the group of plugins/modules in a new collection.
 
 3. When creating a new module or plugin, please make sure that you follow various guidelines:

LICENSES/PSF-2.0.txt

@@ -1,48 +0,0 @@
-PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2
---------------------------------------------
-
-1. This LICENSE AGREEMENT is between the Python Software Foundation
-("PSF"), and the Individual or Organization ("Licensee") accessing and
-otherwise using this software ("Python") in source or binary form and
-its associated documentation.
-
-2. Subject to the terms and conditions of this License Agreement, PSF hereby
-grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce,
-analyze, test, perform and/or display publicly, prepare derivative works,
-distribute, and otherwise use Python alone or in any derivative version,
-provided, however, that PSF's License Agreement and PSF's notice of copyright,
-i.e., "Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010,
-2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021 Python Software Foundation;
-All Rights Reserved" are retained in Python alone or in any derivative version
-prepared by Licensee.
-
-3. In the event Licensee prepares a derivative work that is based on
-or incorporates Python or any part thereof, and wants to make
-the derivative work available to others as provided herein, then
-Licensee hereby agrees to include in any such work a brief summary of
-the changes made to Python.
-
-4. PSF is making Python available to Licensee on an "AS IS"
-basis.  PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
-IMPLIED.  BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND
-DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
-FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON WILL NOT
-INFRINGE ANY THIRD PARTY RIGHTS.
-
-5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON
-FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS
-A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON,
-OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
-
-6. This License Agreement will automatically terminate upon a material
-breach of its terms and conditions.
-
-7. Nothing in this License Agreement shall be deemed to create any
-relationship of agency, partnership, or joint venture between PSF and
-Licensee.  This License Agreement does not grant permission to use PSF
-trademarks or trade name in a trademark sense to endorse or promote
-products or services of Licensee, or any third party.
-
-8. By copying, installing or otherwise using Python, Licensee
-agrees to be bound by the terms and conditions of this License
-Agreement.

README.md

@@ -6,10 +6,10 @@ SPDX-License-Identifier: GPL-3.0-or-later
 
 # Community General Collection
 
-[![Documentation](https://img.shields.io/badge/docs-brightgreen.svg)](https://docs.ansible.com/projects/ansible/latest/collections/community/general/)
-[![Build Status](https://dev.azure.com/ansible/community.general/_apis/build/status/CI?branchName=stable-10)](https://dev.azure.com/ansible/community.general/_build?definitionId=31)
-[![EOL CI](https://github.com/ansible-collections/community.general/actions/workflows/ansible-test.yml/badge.svg?branch=stable-10)](https://github.com/ansible-collections/community.general/actions)
-[![Nox CI](https://github.com/ansible-collections/community.general/actions/workflows/nox.yml/badge.svg?branch=stable-10)](https://github.com/ansible-collections/community.general/actions)
+[![Documentation](https://img.shields.io/badge/docs-brightgreen.svg)](https://docs.ansible.com/projects/ansible/devel/collections/community/general/)
+[![Build Status](https://dev.azure.com/ansible/community.general/_apis/build/status/CI?branchName=stable-12)](https://dev.azure.com/ansible/community.general/_build?definitionId=31)
+[![EOL CI](https://github.com/ansible-collections/community.general/actions/workflows/ansible-test.yml/badge.svg?branch=stable-12)](https://github.com/ansible-collections/community.general/actions)
+[![Nox CI](https://github.com/ansible-collections/community.general/actions/workflows/nox.yml/badge.svg?branch=stable-12)](https://github.com/ansible-collections/community.general/actions)
 [![Codecov](https://img.shields.io/codecov/c/github/ansible-collections/community.general)](https://codecov.io/gh/ansible-collections/community.general)
 [![REUSE status](https://api.reuse.software/badge/github.com/ansible-collections/community.general)](https://api.reuse.software/info/github.com/ansible-collections/community.general)
 
@@ -39,7 +39,7 @@ For more information about communication, see the [Ansible communication guide](
 
 ## Tested with Ansible
 
-Tested with the current ansible-core 2.15, ansible-core 2.16, ansible-core 2.17, ansible-core 2.18, ansible-core 2.19, and ansible-core 2.20 releases. Ansible-core versions before 2.15.0 are not supported. This includes all ansible-base 2.10 and Ansible 2.9 releases.
+Tested with the current ansible-core 2.17, ansible-core 2.18, ansible-core 2.19, ansible-core 2.20 releases and the current development version of ansible-core. Ansible-core versions before 2.17.0 are not supported. This includes all ansible-base 2.10 and Ansible 2.9 releases.
 
 ## External requirements
 
@@ -86,13 +86,13 @@ We are actively accepting new contributors.
 
 All types of contributions are very welcome.
 
-You don't know how to start? Refer to our [contribution guide](https://github.com/ansible-collections/community.general/blob/main/CONTRIBUTING.md)!
+You don't know how to start? Refer to our [contribution guide](https://github.com/ansible-collections/community.general/blob/stable-12/CONTRIBUTING.md)!
 
-The current maintainers are listed in the [commit-rights.md](https://github.com/ansible-collections/community.general/blob/main/commit-rights.md#people) file. If you have questions or need help, feel free to mention them in the proposals.
+The current maintainers are listed in the [commit-rights.md](https://github.com/ansible-collections/community.general/blob/stable-12/commit-rights.md#people) file. If you have questions or need help, feel free to mention them in the proposals.
 
 You can find more information in the [developer guide for collections](https://docs.ansible.com/projects/ansible/devel/dev_guide/developing_collections.html#contributing-to-collections), and in the [Ansible Community Guide](https://docs.ansible.com/projects/ansible/latest/community/index.html).
 
-Also for some notes specific to this collection see [our CONTRIBUTING documentation](https://github.com/ansible-collections/community.general/blob/main/CONTRIBUTING.md).
+Also for some notes specific to this collection see [our CONTRIBUTING documentation](https://github.com/ansible-collections/community.general/blob/stable-12/CONTRIBUTING.md).
 
 ### Running tests
 
@@ -102,8 +102,8 @@ See [here](https://docs.ansible.com/projects/ansible/devel/dev_guide/developing_
 
 To learn how to maintain / become a maintainer of this collection, refer to:
 
-* [Committer guidelines](https://github.com/ansible-collections/community.general/blob/main/commit-rights.md).
-* [Maintainer guidelines](https://github.com/ansible/community-docs/blob/main/maintaining.rst).
+* [Committer guidelines](https://github.com/ansible-collections/community.general/blob/stable-12/commit-rights.md).
+* [Maintainer guidelines](https://github.com/ansible/community-docs/blob/stable-12/maintaining.rst).
 
 It is necessary for maintainers of this collection to be subscribed to:
 
@@ -118,7 +118,7 @@ See the [Releasing guidelines](https://github.com/ansible/community-docs/blob/ma
 
 ## Release notes
 
-See the [changelog](https://github.com/ansible-collections/community.general/blob/stable-10/CHANGELOG.md).
+See the [changelog](https://github.com/ansible-collections/community.general/blob/stable-12/CHANGELOG.md).
 
 ## Roadmap
 
@@ -137,8 +137,8 @@ See [this issue](https://github.com/ansible-collections/community.general/issues
 
 This collection is primarily licensed and distributed as a whole under the GNU General Public License v3.0 or later.
 
-See [LICENSES/GPL-3.0-or-later.txt](https://github.com/ansible-collections/community.general/blob/stable-10/COPYING) for the full text.
+See [LICENSES/GPL-3.0-or-later.txt](https://github.com/ansible-collections/community.general/blob/stable-12/COPYING) for the full text.
 
-Parts of the collection are licensed under the [BSD 2-Clause license](https://github.com/ansible-collections/community.general/blob/stable-10/LICENSES/BSD-2-Clause.txt), the [MIT license](https://github.com/ansible-collections/community.general/blob/stable-10/LICENSES/MIT.txt), and the [PSF 2.0 license](https://github.com/ansible-collections/community.general/blob/stable-10/LICENSES/PSF-2.0.txt).
+Parts of the collection are licensed under the [BSD 2-Clause license](https://github.com/ansible-collections/community.general/blob/stable-12/LICENSES/BSD-2-Clause.txt) and the [MIT license](https://github.com/ansible-collections/community.general/blob/stable-12/LICENSES/MIT.txt).
 
 All files have a machine readable `SDPX-License-Identifier:` comment denoting its respective license(s) or an equivalent entry in an accompanying `.license` file. Only changelog fragments (which will not be part of a release) are covered by a blanket statement in `REUSE.toml`. This conforms to the [REUSE specification](https://reuse.software/spec/).

antsibull-nox.toml

@@ -8,10 +8,6 @@
 "community.docker" = "git+https://github.com/ansible-collections/community.docker.git,main"
 "community.internal_test_tools" = "git+https://github.com/ansible-collections/community.internal_test_tools.git,main"
 
-[collection_sources_per_ansible.'2.15']
-# community.crypto's main branch needs ansible-core >= 2.17
-"community.crypto" = "git+https://github.com/ansible-collections/community.crypto.git,stable-2"
-
 [collection_sources_per_ansible.'2.16']
 # community.crypto's main branch needs ansible-core >= 2.17
 "community.crypto" = "git+https://github.com/ansible-collections/community.crypto.git,stable-2"
@@ -23,8 +19,50 @@ stable_branches = [ "stable-*" ]
 
 [sessions]
 
+[sessions.lint]
+run_isort = false
+run_black = false
+run_ruff_check = true
+ruff_check_config = "ruff.toml"
+run_ruff_format = true
+ruff_format_config = "ruff.toml"
+run_flake8 = false
+run_pylint = false
+run_yamllint = true
+yamllint_config = ".yamllint"
+# yamllint_config_plugins = ".yamllint-docs"
+# yamllint_config_plugins_examples = ".yamllint-examples"
+run_mypy = true
+mypy_ansible_core_package = "ansible-core>=2.19.0"
+mypy_config = ".mypy.ini"
+mypy_extra_deps = [
+    "cryptography",
+    "dnspython",
+    "lxml-stubs",
+    "types-mock",
+    "types-paramiko",
+    "types-passlib",
+    "types-psutil",
+    "types-PyYAML",
+    "types-requests",
+]
+
 [sessions.docs_check]
 validate_collection_refs="all"
+codeblocks_restrict_types = [
+    "ansible-output",
+    "console",
+    "ini",
+    "json",
+    "python",
+    "shell",
+    "yaml",
+    "yaml+jinja",
+    "text",
+]
+codeblocks_restrict_type_exact_case = true
+codeblocks_allow_without_type = false
+codeblocks_allow_literal_blocks = false
 
 [sessions.license_check]
 
@@ -33,6 +71,18 @@ run_no_unwanted_files = true
 no_unwanted_files_module_extensions = [".py"]
 no_unwanted_files_yaml_extensions = [".yml"]
 run_action_groups = true
+run_no_trailing_whitespace = true
+no_trailing_whitespace_skip_paths = [
+    "tests/integration/targets/iso_extract/files/test.iso",
+    "tests/integration/targets/java_cert/files/testpkcs.p12",
+    "tests/integration/targets/one_host/files/testhost/tmp/opennebula-fixtures.json.gz",
+    "tests/integration/targets/one_template/files/testhost/tmp/opennebula-fixtures.json.gz",
+    "tests/integration/targets/setup_flatpak_remote/files/repo.tar.xz",
+]
+no_trailing_whitespace_skip_directories = [
+    "tests/unit/plugins/modules/interfaces_file/interfaces_file_fixtures/golden_output/",
+    "tests/unit/plugins/modules/interfaces_file/interfaces_file_fixtures/input/",
+]
 
 [[sessions.extra_checks.action_groups_config]]
 name = "consul"
@@ -52,10 +102,9 @@ exclusions = [
 doc_fragment = "community.general.keycloak.actiongroup_keycloak"
 
 [[sessions.extra_checks.action_groups_config]]
-name = "proxmox"
-pattern = "^proxmox(_.*)?$"
-exclusions = []
-doc_fragment = "community.general.proxmox.actiongroup_proxmox"
+name = "scaleway"
+pattern = "^scaleway_.*$"
+doc_fragment = "community.general.scaleway.actiongroup_scaleway"
 
 [sessions.build_import_check]
 run_galaxy_importer = true

changelogs/fragments/11909-fix-favicon-url.yml

@@ -1,2 +0,0 @@
-minor_changes:
-  - "mattermost, rocketchat, slack - update default ``icon_url`` to ansible favicon (https://github.com/ansible-collections/community.general/pull/11909)."

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/extra-docs.yml

@@ -8,9 +8,10 @@ sections:
     toctree:
       - filter_guide
       - test_guide
-  - title: Cloud Guides
+  - title: Technology Guides
     toctree:
       - guide_alicloud
+      - guide_iocage
       - guide_online
       - guide_packet
       - guide_scaleway

docs/docsite/helper/keep_keys/README.md

@@ -1,61 +0,0 @@
-<!--
-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
--->
-
-# Docs helper. Create RST file.
-
-The playbook `playbook.yml` writes a RST file that can be used in
-docs/docsite/rst. The usage of this helper is recommended but not
-mandatory. You can stop reading here and update the RST file manually
-if you don't want to use this helper.
-
-## Run the playbook
-
-If you want to generate the RST file by this helper fit the variables
-in the playbook and the template to your needs. Then, run the play
-
-```sh
-shell> ansible-playbook playbook.yml
-```
-
-## Copy RST to docs/docsite/rst
-
-Copy the RST file to `docs/docsite/rst` and remove it from this
-directory.
-
-## Update the checksums
-
-Substitute the variables and run the below commands
-
-```sh
-shell> sha1sum {{ target_vars }} > {{ target_sha1 }}
-shell> sha1sum {{ file_rst }} > {{ file_sha1 }}
-```
-
-## Playbook explained
-
-The playbook includes the variable *tests* from the integration tests
-and creates the RST file from the template. The playbook will
-terminate if:
-
-* The file with the variable *tests* was changed
-* The RST file was changed
-
-This means that this helper is probably not up to date.
-
-### The file with the variable *tests* was changed
-
-This means that somebody updated the integration tests. Review the
-changes and update the template if needed. Update the checksum to pass
-the integrity test. The playbook message provides you with the
-command.
-
-### The RST file was changed
-
-This means that somebody updated the RST file manually. Review the
-changes and update the template. Update the checksum to pass the
-integrity test. The playbook message provides you with the
-command. Make sure that the updated template will create identical RST
-file. Only then apply your changes.

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

@@ -1,80 +0,0 @@
-..
-  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
-
-keep_keys
-"""""""""
-
-Use the filter :ansplugin:`community.general.keep_keys#filter` if you have a list of dictionaries and want to keep certain keys only.
-
-.. note:: The output of the examples in this section use the YAML callback plugin. Quoting: "Ansible output that can be quite a bit easier to read than the default JSON formatting." See :ansplugin:`the documentation for the community.general.yaml callback plugin <community.general.yaml#callback>`.
-
-
-Let us use the below list in the following examples:
-
-.. code-block:: yaml
-
-   input:
-     {{ tests.0.input | to_yaml(indent=2) | indent(5) }}
-
-{% for i in tests[0:1]|subelements('group') %}
-* {{ i.1.d }}
-
-.. code-block:: yaml+jinja
-   :emphasize-lines: 1
-
-   target: {{ i.1.tt }}
-   result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}"
-
-{% endfor %}
-
-gives
-
-.. code-block:: yaml
-   :emphasize-lines: 1-
-
-   result:
-     {{ tests.0.result | to_yaml(indent=2) | indent(5) }}
- 
-.. versionadded:: 9.1.0
-
-* The results of the below examples 1-5 are all the same:
-
-.. code-block:: yaml
-   :emphasize-lines: 1-
-
-   result:
-     {{ tests.1.result | to_yaml(indent=2) | indent(5) }}
-
-{% for i in tests[1:2]|subelements('group') %}
-{{ loop.index }}. {{ i.1.d }}
-
-.. code-block:: yaml+jinja
-   :emphasize-lines: 1,2
-
-   mp: {{ i.1.mp }}
-   target: {{ i.1.tt }}
-   result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}"
-
-{% endfor %}
-
-* The results of the below examples 6-9 are all the same:
-
-.. code-block:: yaml
-   :emphasize-lines: 1-
-
-   result:
-     {{ tests.2.result | to_yaml(indent=2) | indent(5) }}
-
-{% for i in tests[2:3]|subelements('group') %}
-{{ loop.index + 5 }}. {{ i.1.d }}
-
-.. code-block:: yaml+jinja
-   :emphasize-lines: 1,2
-
-   mp: {{ i.1.mp }}
-   target: {{ i.1.tt }}
-   result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}"
-
-{% endfor %}

docs/docsite/helper/keep_keys/keep_keys.rst.sha1

@@ -1 +0,0 @@
-8690afce792abc95693c2f61f743ee27388b1592  ../../rst/filter_guide-abstract_informations-lists_of_dictionaries-keep_keys.rst

docs/docsite/helper/keep_keys/playbook.yml

@@ -1,79 +0,0 @@
----
-# 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
-
-# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-# Create docs REST files
-# shell> ansible-playbook playbook.yml
-#
-# Proofread and copy created *.rst file into the directory
-# docs/docsite/rst. Do not add *.rst in this directory to the version
-# control.
-#
-# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-# community.general/docs/docsite/helper/keep_keys/playbook.yml
-
-- name: Create RST file for docs/docsite/rst
-  hosts: localhost
-  gather_facts: false
-
-  vars:
-
-    plugin: keep_keys
-    plugin_type: filter
-    docs_path:
-      - filter_guide
-      - abstract_informations
-      - lists_of_dictionaries
-
-    file_base: "{{ (docs_path + [plugin]) | join('-') }}"
-    file_rst: ../../rst/{{ file_base }}.rst
-    file_sha1: "{{ plugin }}.rst.sha1"
-
-    target: "../../../../tests/integration/targets/{{ plugin_type }}_{{ plugin }}"
-    target_vars: "{{ target }}/vars/main/tests.yml"
-    target_sha1: tests.yml.sha1
-
-  tasks:
-
-    - name: Test integrity tests.yml
-      when:
-        - integrity | d(true) | bool
-        - lookup('file', target_sha1) != lookup('pipe', 'sha1sum ' ~  target_vars)
-      block:
-
-        - name: Changed tests.yml
-          ansible.builtin.debug:
-            msg: |
-              Changed {{ target_vars }}
-              Review the changes and update {{ target_sha1 }}
-              shell> sha1sum {{ target_vars }} > {{ target_sha1 }}
-
-        - name: Changed tests.yml end host
-          ansible.builtin.meta: end_play
-
-    - name: Test integrity RST file
-      when:
-        - integrity | d(true) | bool
-        - lookup('file', file_sha1) != lookup('pipe', 'sha1sum ' ~ file_rst)
-      block:
-
-        - name: Changed RST file
-          ansible.builtin.debug:
-            msg: |
-              Changed {{ file_rst }}
-              Review the changes and update {{ file_sha1 }}
-              shell> sha1sum {{ file_rst }} > {{ file_sha1 }}
-
-        - name: Changed RST file end host
-          ansible.builtin.meta: end_play
-
-    - name: Include target vars
-      include_vars:
-        file: "{{ target_vars }}"
-
-    - name: Create RST file
-      ansible.builtin.template:
-        src: "{{ file_base }}.rst.j2"
-        dest: "{{ file_base }}.rst"

docs/docsite/helper/keep_keys/tests.yml.sha1

@@ -1 +0,0 @@
-c6fc4ee2017d9222675bcd13cc4f88ba8d14f38d  ../../../../tests/integration/targets/filter_keep_keys/vars/main/tests.yml

docs/docsite/helper/lists_mergeby/default-common.yml

@@ -1,12 +0,0 @@
----
-# 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
-list1:
-  - {name: foo, extra: true}
-  - {name: bar, extra: false}
-  - {name: meh, extra: true}
-
-list2:
-  - {name: foo, path: /foo}
-  - {name: baz, path: /baz}

docs/docsite/helper/lists_mergeby/default-recursive-true.yml

@@ -1,21 +0,0 @@
----
-# 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
-list1:
-  - name: myname01
-    param01:
-      x: default_value
-      y: default_value
-      list: [default_value]
-  - name: myname02
-    param01: [1, 1, 2, 3]
-
-list2:
-  - name: myname01
-    param01:
-      y: patch_value
-      z: patch_value
-      list: [patch_value]
-  - name: myname02
-    param01: [3, 4, 4]

docs/docsite/helper/lists_mergeby/example-001.yml

@@ -1,14 +0,0 @@
----
-# 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: 1. Merge two lists by common attribute 'name'
-  include_vars:
-    dir: example-001_vars
-- debug:
-    var: list3
-  when: debug | d(false) | bool
-- template:
-    src: list3.out.j2
-    dest: example-001.out

docs/docsite/helper/lists_mergeby/example-001_vars/default-common.yml

@@ -1 +0,0 @@
-../default-common.yml

docs/docsite/helper/lists_mergeby/example-002.yml

@@ -1,14 +0,0 @@
----
-# 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: 2. Merge two lists by common attribute 'name'
-  include_vars:
-    dir: example-002_vars
-- debug:
-    var: list3
-  when: debug | d(false) | bool
-- template:
-    src: list3.out.j2
-    dest: example-002.out

docs/docsite/helper/lists_mergeby/example-002_vars/default-common.yml

@@ -1 +0,0 @@
-../default-common.yml

docs/docsite/helper/lists_mergeby/example-002_vars/list3.yml

@@ -1,6 +0,0 @@
----
-# 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
-list3: "{{ [list1, list2] |
-           community.general.lists_mergeby('name') }}"

docs/docsite/helper/lists_mergeby/example-003.yml

@@ -1,14 +0,0 @@
----
-# 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: 3. Merge recursive by 'name', replace lists (default)
-  include_vars:
-    dir: example-003_vars
-- debug:
-    var: list3
-  when: debug | d(false) | bool
-- template:
-    src: list3.out.j2
-    dest: example-003.out

docs/docsite/helper/lists_mergeby/example-003_vars/default-recursive-true.yml

@@ -1 +0,0 @@
-../default-recursive-true.yml

docs/docsite/helper/lists_mergeby/example-003_vars/list3.yml

@@ -1,7 +0,0 @@
----
-# 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
-list3: "{{ [list1, list2] |
-           community.general.lists_mergeby('name',
-                                           recursive=true) }}"

docs/docsite/helper/lists_mergeby/example-004.yml

@@ -1,14 +0,0 @@
----
-# 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: 4. Merge recursive by 'name', keep lists
-  include_vars:
-    dir: example-004_vars
-- debug:
-    var: list3
-  when: debug | d(false) | bool
-- template:
-    src: list3.out.j2
-    dest: example-004.out

docs/docsite/helper/lists_mergeby/example-004_vars/default-recursive-true.yml

@@ -1 +0,0 @@
-../default-recursive-true.yml

docs/docsite/helper/lists_mergeby/example-004_vars/list3.yml

@@ -1,8 +0,0 @@
----
-# 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
-list3: "{{ [list1, list2] |
-           community.general.lists_mergeby('name',
-                                           recursive=true,
-                                           list_merge='keep') }}"

docs/docsite/helper/lists_mergeby/example-005.yml

@@ -1,14 +0,0 @@
----
-# 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: 5. Merge recursive by 'name', append lists
-  include_vars:
-    dir: example-005_vars
-- debug:
-    var: list3
-  when: debug | d(false) | bool
-- template:
-    src: list3.out.j2
-    dest: example-005.out

docs/docsite/helper/lists_mergeby/example-005_vars/default-recursive-true.yml

@@ -1 +0,0 @@
-../default-recursive-true.yml

docs/docsite/helper/lists_mergeby/example-005_vars/list3.yml

@@ -1,8 +0,0 @@
----
-# 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
-list3: "{{ [list1, list2] |
-           community.general.lists_mergeby('name',
-                                           recursive=true,
-                                           list_merge='append') }}"

docs/docsite/helper/lists_mergeby/example-006.yml

@@ -1,14 +0,0 @@
----
-# 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: 6. Merge recursive by 'name', prepend lists
-  include_vars:
-    dir: example-006_vars
-- debug:
-    var: list3
-  when: debug | d(false) | bool
-- template:
-    src: list3.out.j2
-    dest: example-006.out

docs/docsite/helper/lists_mergeby/example-006_vars/default-recursive-true.yml

@@ -1 +0,0 @@
-../default-recursive-true.yml

docs/docsite/helper/lists_mergeby/example-006_vars/list3.yml

@@ -1,8 +0,0 @@
----
-# 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
-list3: "{{ [list1, list2] |
-           community.general.lists_mergeby('name',
-                                           recursive=true,
-                                           list_merge='prepend') }}"

docs/docsite/helper/lists_mergeby/example-007.yml

@@ -1,14 +0,0 @@
----
-# 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: 7. Merge recursive by 'name', append lists 'remove present'
-  include_vars:
-    dir: example-007_vars
-- debug:
-    var: list3
-  when: debug|d(false) | bool
-- template:
-    src: list3.out.j2
-    dest: example-007.out

docs/docsite/helper/lists_mergeby/example-007_vars/default-recursive-true.yml

@@ -1 +0,0 @@
-../default-recursive-true.yml

docs/docsite/helper/lists_mergeby/example-007_vars/list3.yml

@@ -1,8 +0,0 @@
----
-# 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
-list3: "{{ [list1, list2] |
-           community.general.lists_mergeby('name',
-                                           recursive=true,
-                                           list_merge='append_rp') }}"

docs/docsite/helper/lists_mergeby/example-008.yml

@@ -1,14 +0,0 @@
----
-# 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: 8. Merge recursive by 'name', prepend lists 'remove present'
-  include_vars:
-    dir: example-008_vars
-- debug:
-    var: list3
-  when: debug | d(false) | bool
-- template:
-    src: list3.out.j2
-    dest: example-008.out

docs/docsite/helper/lists_mergeby/example-008_vars/default-recursive-true.yml

@@ -1 +0,0 @@
-../default-recursive-true.yml

docs/docsite/helper/lists_mergeby/example-008_vars/list3.yml

@@ -1,8 +0,0 @@
----
-# 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
-list3: "{{ [list1, list2] |
-           community.general.lists_mergeby('name',
-                                           recursive=true,
-                                           list_merge='prepend_rp') }}"

docs/docsite/helper/lists_mergeby/example-009.yml

@@ -1,14 +0,0 @@
----
-# 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: 9. Merge single list by common attribute 'name'
-  include_vars:
-    dir: example-009_vars
-- debug:
-    var: list3
-  when: debug | d(false) | bool
-- template:
-    src: list3.out.j2
-    dest: example-009.out

docs/docsite/helper/lists_mergeby/example-009_vars/default-common.yml

@@ -1 +0,0 @@
-../default-common.yml

docs/docsite/helper/lists_mergeby/example-009_vars/list3.yml

@@ -1,6 +0,0 @@
----
-# 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
-list3: "{{ [list1 + list2, []] |
-           community.general.lists_mergeby('name') }}"

docs/docsite/helper/lists_mergeby/examples.yml

@@ -1,78 +0,0 @@
----
-# 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
-
-examples:
-  - title: Two lists
-    description: 'In the example below the lists are merged by the attribute ``name``:'
-    file: example-001_vars/list3.yml
-    lang: 'yaml+jinja'
-  - title:
-    description: 'This produces:'
-    file: example-001.out
-    lang: 'yaml'
-  - title: List of two lists
-    description: 'It is possible to use a list of lists as an input of the filter:'
-    file: example-002_vars/list3.yml
-    lang: 'yaml+jinja'
-  - title:
-    description: 'This produces the same result as in the previous example:'
-    file: example-002.out
-    lang: 'yaml'
-  - title: Single list
-    description: 'It is possible to merge single list:'
-    file: example-009_vars/list3.yml
-    lang: 'yaml+jinja'
-  - title:
-    description: 'This produces the same result as in the previous example:'
-    file: example-009.out
-    lang: 'yaml'
-  - title: list_merge=replace (default)
-    description: 'Example :ansopt:`community.general.lists_mergeby#filter:list_merge=replace` (default):'
-    file: example-003_vars/list3.yml
-    lang: 'yaml+jinja'
-  - title:
-    description: 'This produces:'
-    file: example-003.out
-    lang: 'yaml'
-  - title: list_merge=keep
-    description: 'Example :ansopt:`community.general.lists_mergeby#filter:list_merge=keep`:'
-    file: example-004_vars/list3.yml
-    lang: 'yaml+jinja'
-  - title:
-    description: 'This produces:'
-    file: example-004.out
-    lang: 'yaml'
-  - title: list_merge=append
-    description: 'Example :ansopt:`community.general.lists_mergeby#filter:list_merge=append`:'
-    file: example-005_vars/list3.yml
-    lang: 'yaml+jinja'
-  - title:
-    description: 'This produces:'
-    file: example-005.out
-    lang: 'yaml'
-  - title: list_merge=prepend
-    description: 'Example :ansopt:`community.general.lists_mergeby#filter:list_merge=prepend`:'
-    file: example-006_vars/list3.yml
-    lang: 'yaml+jinja'
-  - title:
-    description: 'This produces:'
-    file: example-006.out
-    lang: 'yaml'
-  - title: list_merge=append_rp
-    description: 'Example :ansopt:`community.general.lists_mergeby#filter:list_merge=append_rp`:'
-    file: example-007_vars/list3.yml
-    lang: 'yaml+jinja'
-  - title:
-    description: 'This produces:'
-    file: example-007.out
-    lang: 'yaml'
-  - title: list_merge=prepend_rp
-    description: 'Example :ansopt:`community.general.lists_mergeby#filter:list_merge=prepend_rp`:'
-    file: example-008_vars/list3.yml
-    lang: 'yaml+jinja'
-  - title:
-    description: 'This produces:'
-    file: example-008.out
-    lang: 'yaml'

docs/docsite/helper/lists_mergeby/filter_guide_abstract_informations_merging_lists_of_dictionaries.rst.j2

@@ -1,74 +0,0 @@
-..
-  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
-
-Merging lists of dictionaries
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If you have two or more lists of dictionaries and want to combine them into a list of merged dictionaries, where the dictionaries are merged by an attribute, you can use the :ansplugin:`community.general.lists_mergeby <community.general.lists_mergeby#filter>` filter.
-
-.. note:: The output of the examples in this section use the YAML callback plugin. Quoting: "Ansible output that can be quite a bit easier to read than the default JSON formatting." See the documentation for the :ansplugin:`community.general.yaml callback plugin <community.general.yaml#callback>`.
-
-Let us use the lists below in the following examples:
-
-.. code-block:: yaml
-
-  {{ lookup('file', 'default-common.yml') | split('\n') | reject('match', '^(#|---)') | join ('\n')  | indent(2) }}
-
-{% for i in examples[0:2] %}
-{% if i.title | d('', true) | length > 0 %}
-{{ i.title }}
-{{ "%s" % ('"' * i.title|length) }}
-{% endif %}
-{{ i.description }}
-
-.. code-block:: {{ i.lang }}
-
-  {{ lookup('file', i.file) | split('\n') | reject('match', '^(#|---)') | join ('\n') | indent(2) }}
-
-{% endfor %}
-
-.. versionadded:: 2.0.0
-
-{% for i in examples[2:6] %}
-{% if i.title | d('', true) | length > 0 %}
-{{ i.title }}
-{{ "%s" % ('"' * i.title|length) }}
-{% endif %}
-{{ i.description }}
-
-.. code-block:: {{ i.lang }}
-
-  {{ lookup('file', i.file) | split('\n') | reject('match', '^(#|---)') | join ('\n') | indent(2) }}
-
-{% endfor %}
-
-The filter also accepts two optional parameters: :ansopt:`community.general.lists_mergeby#filter:recursive` and :ansopt:`community.general.lists_mergeby#filter:list_merge`. This is available since community.general 4.4.0.
-
-**recursive**
-    Is a boolean, default to ``false``. Should the :ansplugin:`community.general.lists_mergeby#filter` filter recursively merge nested hashes. Note: It does not depend on the value of the ``hash_behaviour`` setting in ``ansible.cfg``.
-
-**list_merge**
-    Is a string, its possible values are :ansval:`replace` (default), :ansval:`keep`, :ansval:`append`, :ansval:`prepend`, :ansval:`append_rp` or :ansval:`prepend_rp`. It modifies the behaviour of :ansplugin:`community.general.lists_mergeby#filter` when the hashes to merge contain arrays/lists.
-
-The examples below set :ansopt:`community.general.lists_mergeby#filter:recursive=true` and display the differences among all six options of :ansopt:`community.general.lists_mergeby#filter:list_merge`. Functionality of the parameters is exactly the same as in the filter :ansplugin:`ansible.builtin.combine#filter`. See :ref:`Combining hashes/dictionaries <combine_filter>` to learn details about these options.
-
-Let us use the lists below in the following examples
-
-.. code-block:: yaml
-
-  {{ lookup('file', 'default-recursive-true.yml') | split('\n') | reject('match', '^(#|---)') | join ('\n') |indent(2) }}
-
-{% for i in examples[6:] %}
-{% if i.title | d('', true) | length > 0 %}
-{{ i.title }}
-{{ "%s" % ('"' * i.title|length) }}
-{% endif %}
-{{ i.description }}
-
-.. code-block:: {{ i.lang }}
-
-  {{ lookup('file', i.file) | split('\n') | reject('match', '^(#|---)') | join ('\n') |indent(2) }}
-
-{% endfor %}

docs/docsite/helper/lists_mergeby/list3.out.j2

@@ -1,7 +0,0 @@
-{#
-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
-#}
-list3:
-  {{ list3 | to_yaml(indent=2, sort_keys=false) | indent(2) }}

docs/docsite/helper/lists_mergeby/playbook.yml

@@ -1,64 +0,0 @@
----
-# 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
-
-# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-# 1) Run all examples and create example-XXX.out
-# shell> ansible-playbook playbook.yml -e examples_one=true
-#
-# 2) Optionally, for testing, create examples_all.rst
-# shell> ansible-playbook playbook.yml -e examples_all=true
-#
-# 3) Create docs REST files
-# shell> ansible-playbook playbook.yml -e merging_lists_of_dictionaries=true
-#
-# Notes:
-# * Use YAML callback, e.g. set ANSIBLE_STDOUT_CALLBACK=community.general.yaml
-# * Use sphinx-view to render and review the REST files
-#   shell> sphinx-view <path_to_helper>/examples_all.rst
-# * Proofread and copy completed docs *.rst files into the directory rst.
-# * Then delete the *.rst and *.out files from this directory. Do not
-#   add *.rst and *.out in this directory to the version control.
-#
-# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-# community.general/docs/docsite/helper/lists_mergeby/playbook.yml
-
-- hosts: localhost
-  gather_facts: false
-  tasks:
-
-    - block:
-        - import_tasks: example-001.yml
-          tags: t001
-        - import_tasks: example-002.yml
-          tags: t002
-        - import_tasks: example-003.yml
-          tags: t003
-        - import_tasks: example-004.yml
-          tags: t004
-        - import_tasks: example-005.yml
-          tags: t005
-        - import_tasks: example-006.yml
-          tags: t006
-        - import_tasks: example-007.yml
-          tags: t007
-        - import_tasks: example-008.yml
-          tags: t008
-        - import_tasks: example-009.yml
-          tags: t009
-      when: examples_one | d(false) | bool
-
-    - block:
-        - include_vars: examples.yml
-        - template:
-            src: examples_all.rst.j2
-            dest: examples_all.rst
-      when: examples_all | d(false) | bool
-
-    - block:
-        - include_vars: examples.yml
-        - template:
-            src: filter_guide_abstract_informations_merging_lists_of_dictionaries.rst.j2
-            dest: filter_guide_abstract_informations_merging_lists_of_dictionaries.rst
-      when: merging_lists_of_dictionaries | d(false) | bool

docs/docsite/helper/remove_keys/README.md

@@ -1,61 +0,0 @@
-<!--
-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
--->
-
-# Docs helper. Create RST file.
-
-The playbook `playbook.yml` writes a RST file that can be used in
-docs/docsite/rst. The usage of this helper is recommended but not
-mandatory. You can stop reading here and update the RST file manually
-if you don't want to use this helper.
-
-## Run the playbook
-
-If you want to generate the RST file by this helper fit the variables
-in the playbook and the template to your needs. Then, run the play
-
-```sh
-shell> ansible-playbook playbook.yml
-```
-
-## Copy RST to docs/docsite/rst
-
-Copy the RST file to `docs/docsite/rst` and remove it from this
-directory.
-
-## Update the checksums
-
-Substitute the variables and run the below commands
-
-```sh
-shell> sha1sum {{ target_vars }} > {{ target_sha1 }}
-shell> sha1sum {{ file_rst }} > {{ file_sha1 }}
-```
-
-## Playbook explained
-
-The playbook includes the variable *tests* from the integration tests
-and creates the RST file from the template. The playbook will
-terminate if:
-
-* The file with the variable *tests* was changed
-* The RST file was changed
-
-This means that this helper is probably not up to date.
-
-### The file with the variable *tests* was changed
-
-This means that somebody updated the integration tests. Review the
-changes and update the template if needed. Update the checksum to pass
-the integrity test. The playbook message provides you with the
-command.
-
-### The RST file was changed
-
-This means that somebody updated the RST file manually. Review the
-changes and update the template. Update the checksum to pass the
-integrity test. The playbook message provides you with the
-command. Make sure that the updated template will create identical RST
-file. Only then apply your changes.

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

@@ -1,80 +0,0 @@
-..
-  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
-
-remove_keys
-"""""""""""
-
-Use the filter :ansplugin:`community.general.remove_keys#filter` if you have a list of dictionaries and want to remove certain keys.
-
-.. note:: The output of the examples in this section use the YAML callback plugin. Quoting: "Ansible output that can be quite a bit easier to read than the default JSON formatting." See See :ansplugin:`the documentation for the community.general.yaml callback plugin <community.general.yaml#callback>`.
-
-
-Let us use the below list in the following examples:
-
-.. code-block:: yaml
-
-   input:
-     {{ tests.0.input | to_yaml(indent=2) | indent(5) }}
-
-{% for i in tests[0:1]|subelements('group') %}
-* {{ i.1.d }}
-
-.. code-block:: yaml+jinja
-   :emphasize-lines: 1
-
-   target: {{ i.1.tt }}
-   result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}"
-
-{% endfor %}
-
-gives
-
-.. code-block:: yaml
-   :emphasize-lines: 1-
-
-   result:
-     {{ tests.0.result | to_yaml(indent=2) | indent(5) }}
- 
-.. versionadded:: 9.1.0
-
-* The results of the below examples 1-5 are all the same:
-
-.. code-block:: yaml
-   :emphasize-lines: 1-
-
-   result:
-     {{ tests.1.result | to_yaml(indent=2) | indent(5) }}
-
-{% for i in tests[1:2]|subelements('group') %}
-{{ loop.index }}. {{ i.1.d }}
-
-.. code-block:: yaml+jinja
-   :emphasize-lines: 1,2
-
-   mp: {{ i.1.mp }}
-   target: {{ i.1.tt }}
-   result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}"
-
-{% endfor %}
-
-* The results of the below examples 6-9 are all the same:
-
-.. code-block:: yaml
-   :emphasize-lines: 1-
-
-   result:
-     {{ tests.2.result | to_yaml(indent=2) | indent(5) }}
-
-{% for i in tests[2:3]|subelements('group') %}
-{{ loop.index + 5 }}. {{ i.1.d }}
-
-.. code-block:: yaml+jinja
-   :emphasize-lines: 1,2
-
-   mp: {{ i.1.mp }}
-   target: {{ i.1.tt }}
-   result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}"
-
-{% endfor %}

docs/docsite/helper/remove_keys/playbook.yml

@@ -1,79 +0,0 @@
----
-# 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
-
-# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-# Create docs REST files
-# shell> ansible-playbook playbook.yml
-#
-# Proofread and copy created *.rst file into the directory
-# docs/docsite/rst. Do not add *.rst in this directory to the version
-# control.
-#
-# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-# community.general/docs/docsite/helper/remove_keys/playbook.yml
-
-- name: Create RST file for docs/docsite/rst
-  hosts: localhost
-  gather_facts: false
-
-  vars:
-
-    plugin: remove_keys
-    plugin_type: filter
-    docs_path:
-      - filter_guide
-      - abstract_informations
-      - lists_of_dictionaries
-
-    file_base: "{{ (docs_path + [plugin]) | join('-') }}"
-    file_rst: ../../rst/{{ file_base }}.rst
-    file_sha1: "{{ plugin }}.rst.sha1"
-
-    target: "../../../../tests/integration/targets/{{ plugin_type }}_{{ plugin }}"
-    target_vars: "{{ target }}/vars/main/tests.yml"
-    target_sha1: tests.yml.sha1
-
-  tasks:
-
-    - name: Test integrity tests.yml
-      when:
-        - integrity | d(true) | bool
-        - lookup('file', target_sha1) != lookup('pipe', 'sha1sum ' ~  target_vars)
-      block:
-
-        - name: Changed tests.yml
-          ansible.builtin.debug:
-            msg: |
-              Changed {{ target_vars }}
-              Review the changes and update {{ target_sha1 }}
-              shell> sha1sum {{ target_vars }} > {{ target_sha1 }}
-
-        - name: Changed tests.yml end host
-          ansible.builtin.meta: end_play
-
-    - name: Test integrity RST file
-      when:
-        - integrity | d(true) | bool
-        - lookup('file', file_sha1) != lookup('pipe', 'sha1sum ' ~ file_rst)
-      block:
-
-        - name: Changed RST file
-          ansible.builtin.debug:
-            msg: |
-              Changed {{ file_rst }}
-              Review the changes and update {{ file_sha1 }}
-              shell> sha1sum {{ file_rst }} > {{ file_sha1 }}
-
-        - name: Changed RST file end host
-          ansible.builtin.meta: end_play
-
-    - name: Include target vars
-      include_vars:
-        file: "{{ target_vars }}"
-
-    - name: Create RST file
-      ansible.builtin.template:
-        src: "{{ file_base }}.rst.j2"
-        dest: "{{ file_base }}.rst"

docs/docsite/helper/remove_keys/remove_keys.rst.sha1

@@ -1 +0,0 @@
-3cc606b42e3d450cf6323f25930f7c5a591fa086  ../../rst/filter_guide-abstract_informations-lists_of_dictionaries-remove_keys.rst

docs/docsite/helper/remove_keys/tests.yml.sha1

@@ -1 +0,0 @@
-0554335045f02d8c37b824355b0cf86864cee9a5  ../../../../tests/integration/targets/filter_remove_keys/vars/main/tests.yml

docs/docsite/helper/remove_keys/tests.yml.sha1.license

@@ -1,3 +0,0 @@
-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

docs/docsite/helper/replace_keys/README.md

@@ -1,61 +0,0 @@
-<!--
-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
--->
-
-# Docs helper. Create RST file.
-
-The playbook `playbook.yml` writes a RST file that can be used in
-docs/docsite/rst. The usage of this helper is recommended but not
-mandatory. You can stop reading here and update the RST file manually
-if you don't want to use this helper.
-
-## Run the playbook
-
-If you want to generate the RST file by this helper fit the variables
-in the playbook and the template to your needs. Then, run the play
-
-```sh
-shell> ansible-playbook playbook.yml
-```
-
-## Copy RST to docs/docsite/rst
-
-Copy the RST file to `docs/docsite/rst` and remove it from this
-directory.
-
-## Update the checksums
-
-Substitute the variables and run the below commands
-
-```sh
-shell> sha1sum {{ target_vars }} > {{ target_sha1 }}
-shell> sha1sum {{ file_rst }} > {{ file_sha1 }}
-```
-
-## Playbook explained
-
-The playbook includes the variable *tests* from the integration tests
-and creates the RST file from the template. The playbook will
-terminate if:
-
-* The file with the variable *tests* was changed
-* The RST file was changed
-
-This means that this helper is probably not up to date.
-
-### The file with the variable *tests* was changed
-
-This means that somebody updated the integration tests. Review the
-changes and update the template if needed. Update the checksum to pass
-the integrity test. The playbook message provides you with the
-command.
-
-### The RST file was changed
-
-This means that somebody updated the RST file manually. Review the
-changes and update the template. Update the checksum to pass the
-integrity test. The playbook message provides you with the
-command. Make sure that the updated template will create identical RST
-file. Only then apply your changes.

docs/docsite/helper/replace_keys/filter_guide-abstract_informations-lists_of_dictionaries-replace_keys.rst.j2

@@ -1,110 +0,0 @@
-..
-  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
-
-replace_keys
-""""""""""""
-
-Use the filter :ansplugin:`community.general.replace_keys#filter` if you have a list of dictionaries and want to replace certain keys.
-
-.. note:: The output of the examples in this section use the YAML callback plugin. Quoting: "Ansible output that can be quite a bit easier to read than the default JSON formatting." See :ansplugin:`the documentation for the community.general.yaml callback plugin <community.general.yaml#callback>`.
-
-
-Let us use the below list in the following examples:
-
-.. code-block:: yaml
-
-   input:
-     {{ tests.0.input | to_yaml(indent=2) | indent(5) }}
-
-{% for i in tests[0:1]|subelements('group') %}
-* {{ i.1.d }}
-
-.. code-block:: yaml+jinja
-   :emphasize-lines: 1-3
-
-   target:
-     {{ i.1.tt | to_yaml(indent=2) | indent(5) }}
-   result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}"
-
-{% endfor %}
-
-gives
-
-.. code-block:: yaml
-   :emphasize-lines: 1-
-
-   result:
-     {{ tests.0.result | to_yaml(indent=2) | indent(5) }}
- 
-.. versionadded:: 9.1.0
-
-* The results of the below examples 1-3 are all the same:
-
-.. code-block:: yaml
-   :emphasize-lines: 1-
-
-   result:
-     {{ tests.1.result | to_yaml(indent=2) | indent(5) }}
-
-{% for i in tests[1:2]|subelements('group') %}
-{{ loop.index }}. {{ i.1.d }}
-
-.. code-block:: yaml+jinja
-   :emphasize-lines: 1-4
-
-   mp: {{ i.1.mp }}
-   target:
-     {{ i.1.tt | to_yaml(indent=2) | indent(5) }}
-   result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}"
-
-{% endfor %}
-
-* The results of the below examples 4-5 are the same:
-
-.. code-block:: yaml
-   :emphasize-lines: 1-
-
-   result:
-     {{ tests.2.result | to_yaml(indent=2) | indent(5) }}
-
-{% for i in tests[2:3]|subelements('group') %}
-{{ loop.index + 3 }}. {{ i.1.d }}
-
-.. code-block:: yaml+jinja
-   :emphasize-lines: 1-3
-
-   mp: {{ i.1.mp }}
-   target:
-     {{ i.1.tt | to_yaml(indent=2) | indent(5) }}
-   result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}"
-
-{% endfor %}
-
-{% for i in tests[3:4]|subelements('group') %}
-{{ loop.index + 5 }}. {{ i.1.d }}
-
-.. code-block:: yaml
-   :emphasize-lines: 1-
-
-   input:
-     {{ i.0.input | to_yaml(indent=2) | indent(5) }}
-
-.. code-block:: yaml+jinja
-   :emphasize-lines: 1-4
-
-   mp: {{ i.1.mp }}
-   target:
-     {{ i.1.tt | to_yaml(indent=2) | indent(5) }}
-   result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}"
-
-gives
-
-.. code-block:: yaml
-   :emphasize-lines: 1-
-
-   result:
-     {{ i.0.result | to_yaml(indent=2) | indent(5) }}
-
-{% endfor %}

docs/docsite/helper/replace_keys/playbook.yml

@@ -1,79 +0,0 @@
----
-# 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
-
-# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-# Create docs REST files
-# shell> ansible-playbook playbook.yml
-#
-# Proofread and copy created *.rst file into the directory
-# docs/docsite/rst. Do not add *.rst in this directory to the version
-# control.
-#
-# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-# community.general/docs/docsite/helper/replace_keys/playbook.yml
-
-- name: Create RST file for docs/docsite/rst
-  hosts: localhost
-  gather_facts: false
-
-  vars:
-
-    plugin: replace_keys
-    plugin_type: filter
-    docs_path:
-      - filter_guide
-      - abstract_informations
-      - lists_of_dictionaries
-
-    file_base: "{{ (docs_path + [plugin]) | join('-') }}"
-    file_rst: ../../rst/{{ file_base }}.rst
-    file_sha1: "{{ plugin }}.rst.sha1"
-
-    target: "../../../../tests/integration/targets/{{ plugin_type }}_{{ plugin }}"
-    target_vars: "{{ target }}/vars/main/tests.yml"
-    target_sha1: tests.yml.sha1
-
-  tasks:
-
-    - name: Test integrity tests.yml
-      when:
-        - integrity | d(true) | bool
-        - lookup('file', target_sha1) != lookup('pipe', 'sha1sum ' ~  target_vars)
-      block:
-
-        - name: Changed tests.yml
-          ansible.builtin.debug:
-            msg: |
-              Changed {{ target_vars }}
-              Review the changes and update {{ target_sha1 }}
-              shell> sha1sum {{ target_vars }} > {{ target_sha1 }}
-
-        - name: Changed tests.yml end host
-          ansible.builtin.meta: end_play
-
-    - name: Test integrity RST file
-      when:
-        - integrity | d(true) | bool
-        - lookup('file', file_sha1) != lookup('pipe', 'sha1sum ' ~ file_rst)
-      block:
-
-        - name: Changed RST file
-          ansible.builtin.debug:
-            msg: |
-              Changed {{ file_rst }}
-              Review the changes and update {{ file_sha1 }}
-              shell> sha1sum {{ file_rst }} > {{ file_sha1 }}
-
-        - name: Changed RST file end host
-          ansible.builtin.meta: end_play
-
-    - name: Include target vars
-      include_vars:
-        file: "{{ target_vars }}"
-
-    - name: Create RST file
-      ansible.builtin.template:
-        src: "{{ file_base }}.rst.j2"
-        dest: "{{ file_base }}.rst"

docs/docsite/helper/replace_keys/replace_keys.rst.sha1

@@ -1 +0,0 @@
-403f23c02ac02b1c3b611cb14f9b3ba59dc3f587  ../../rst/filter_guide-abstract_informations-lists_of_dictionaries-replace_keys.rst

docs/docsite/helper/replace_keys/replace_keys.rst.sha1.license

@@ -1,3 +0,0 @@
-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

docs/docsite/helper/replace_keys/tests.yml.sha1

@@ -1 +0,0 @@
-2e54f3528c95cca746d5748f1ed7ada56ad0890e  ../../../../tests/integration/targets/filter_replace_keys/vars/main/tests.yml

docs/docsite/reformat-yaml.py

@@ -0,0 +1,26 @@
+#!/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)
+
+    # 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) }}"
-

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

@@ -13,6 +13,34 @@ Use the filter :ansplugin:`community.general.replace_keys#filter` if you have a
 
 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:
@@ -40,35 +68,61 @@ Let us use the below list in the following examples:
 
 gives
 
+.. ansible-output-data::
+
+    playbook: ~
+
 .. code-block:: yaml
    :emphasize-lines: 1-
 
    result:
      - a0: A0
        a1: B0
-       k2_x2: [C0]
+       k2_x2:
+         - C0
        k3_x3: foo
      - a0: A1
        a1: B1
-       k2_x2: [C1]
+       k2_x2:
+         - C1
        k3_x3: bar
 
- 
+
 .. versionadded:: 9.1.0
 
 * The results of the below examples 1-3 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: starts_with
+              target:
+                - {after: a0, before: k0}
+                - {after: a1, before: k1}
+              result: "{{ input | community.general.replace_keys(target=target, matching_parameter=mp) }}"
+            ansible.builtin.debug:
+              var: result
+
 .. code-block:: yaml
    :emphasize-lines: 1-
 
    result:
      - a0: A0
        a1: B0
-       k2_x2: [C0]
+       k2_x2:
+         - C0
        k3_x3: foo
      - a0: A1
        a1: B1
-       k2_x2: [C1]
+       k2_x2:
+         - C1
        k3_x3: bar
 
 
@@ -111,12 +165,29 @@ gives
 
 * The results of the below examples 4-5 are the same:
 
+.. ansible-output-data::
+
+    playbook: |-
+      - hosts: localhost
+        gather_facts: false
+        tasks:
+          - vars:
+              @{{ data | indent(8) }}@
+
+              # I picked one of the examples
+              mp: regex
+              target:
+                - {after: X, before: ^.*_x.*$}
+              result: "{{ input | community.general.replace_keys(target=target, matching_parameter=mp) }}"
+            ansible.builtin.debug:
+              var: result
+
 .. code-block:: yaml
    :emphasize-lines: 1-
 
    result:
-     - {X: foo}
-     - {X: bar}
+     - X: foo
+     - X: bar
 
 
 4. If more keys match the same attribute before the last one will be used.
@@ -145,6 +216,11 @@ gives
 
 6. If there are more matches for a key the first one will be used.
 
+.. ansible-output-meta::
+
+  actions:
+    - name: reset-previous-blocks
+
 .. code-block:: yaml
    :emphasize-lines: 1-
 
@@ -165,11 +241,17 @@ gives
 
 gives
 
+.. ansible-output-data::
+
+    playbook: ~
+
 .. code-block:: yaml
    :emphasize-lines: 1-
 
    result:
-     - {X: A, bbb1: B, ccc1: C}
-     - {X: D, bbb2: E, ccc2: F}
-
-
+     - X: A
+       bbb1: B
+       ccc1: C
+     - X: D
+       bbb2: E
+       ccc2: F

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

@@ -4,7 +4,7 @@
   SPDX-License-Identifier: GPL-3.0-or-later
 
 .. _ansible_collections.community.general.docsite.filter_guide.filter_guide_abstract_informations.lists_of_dicts:
-  
+
 Lists of dictionaries
 ^^^^^^^^^^^^^^^^^^^^^
 

docs/docsite/rst/filter_guide_abstract_informations_counting_elements_in_sequence.rst

@@ -20,6 +20,17 @@ The :ansplugin:`community.general.counter filter plugin <community.general.count
 
 This produces:
 
+.. ansible-output-data::
+
+    variables:
+      task:
+        previous_code_block: yaml+jinja
+    playbook: |-
+      - hosts: localhost
+        gather_facts: false
+        tasks:
+          @{{ task | indent(4) }}@
+
 .. code-block:: ansible-output
 
     TASK [Count character occurrences in a string] ********************************************
@@ -72,9 +83,20 @@ This plugin is useful for selecting resources based on current allocation:
 
 This produces:
 
+.. ansible-output-data::
+
+    variables:
+      task:
+        previous_code_block: yaml+jinja
+    playbook: |-
+      - hosts: localhost
+        gather_facts: false
+        tasks:
+          @{{ task | indent(4) }}@
+
 .. code-block:: ansible-output
 
-    TASK [Get ID of SCSI controller(s) with less than 4 disks attached and choose the one with the least disks]
+    TASK [Get ID of SCSI controller(s) with less than 4 disks attached and choose the one with the least disks] ***
     ok: [localhost] => {
         "msg": "scsi_2"
     }

docs/docsite/rst/filter_guide_abstract_informations_dictionaries.rst

@@ -31,16 +31,27 @@ You can use the :ansplugin:`community.general.dict_kv filter <community.general.
 
 This produces:
 
+.. ansible-output-data::
+
+    variables:
+      task:
+        previous_code_block: yaml+jinja
+    playbook: |-
+      - hosts: localhost
+        gather_facts: false
+        tasks:
+          @{{ task | indent(4) }}@
+
 .. code-block:: ansible-output
 
-    TASK [Create a single-entry dictionary]  **************************************************
+    TASK [Create a single-entry dictionary] ***************************************************
     ok: [localhost] => {
         "msg": {
             "thatsmyvar": "myvalue"
         }
     }
 
-    TASK [Create a list of dictionaries where the 'server' field is taken from a list]  *******
+    TASK [Create a list of dictionaries where the 'server' field is taken from a list] ********
     ok: [localhost] => {
         "msg": [
             {
@@ -87,9 +98,20 @@ If you need to convert a list of key-value pairs to a dictionary, you can use th
 
 This produces:
 
+.. ansible-output-data::
+
+    variables:
+      task:
+        previous_code_block: yaml+jinja
+    playbook: |-
+      - hosts: localhost
+        gather_facts: false
+        tasks:
+          @{{ task | indent(4) }}@
+
 .. code-block:: ansible-output
 
-    TASK [Create a dictionary with the dict function]  ****************************************
+    TASK [Create a dictionary with the dict function] *****************************************
     ok: [localhost] => {
         "msg": {
             "1": 2,
@@ -97,7 +119,7 @@ This produces:
         }
     }
 
-    TASK [Create a dictionary with the community.general.dict filter]  ************************
+    TASK [Create a dictionary with the community.general.dict filter] *************************
     ok: [localhost] => {
         "msg": {
             "1": 2,
@@ -105,7 +127,7 @@ This produces:
         }
     }
 
-    TASK [Create a list of dictionaries with map and the community.general.dict filter]  ******
+    TASK [Create a list of dictionaries with map and the community.general.dict filter] *******
     ok: [localhost] => {
         "msg": [
             {

docs/docsite/rst/filter_guide_abstract_informations_grouping.rst

@@ -22,6 +22,49 @@ One example is ``ansible_facts.mounts``, which is a list of dictionaries where e
 
 This produces:
 
+.. ansible-output-data::
+
+    variables:
+      task:
+        previous_code_block: yaml+jinja
+    skip_first_lines: 3  # the set_fact task
+    playbook: |-
+      - hosts: localhost
+        gather_facts: false
+        tasks:
+          - ansible.builtin.set_fact:
+              ansible_facts:
+                mounts:
+                  - block_available: 2000
+                    block_size: 4096
+                    block_total: 2345
+                    block_used: 345
+                    device: "/dev/sda1"
+                    fstype: "ext4"
+                    inode_available: 500
+                    inode_total: 512
+                    inode_used: 12
+                    mount: "/boot"
+                    options: "rw,relatime,data=ordered"
+                    size_available: 56821
+                    size_total: 543210
+                    uuid: "ab31cade-d9c1-484d-8482-8a4cbee5241a"
+                  - block_available: 1234
+                    block_size: 4096
+                    block_total: 12345
+                    block_used: 11111
+                    device: "/dev/sda2"
+                    fstype: "ext4"
+                    inode_available: 1111
+                    inode_total: 1234
+                    inode_used: 123
+                    mount: "/"
+                    options: "rw,relatime"
+                    size_available: 42143
+                    size_total: 543210
+                    uuid: "abcdef01-2345-6789-0abc-def012345678"
+          @{{ task | indent(4) }}@
+
 .. code-block:: ansible-output
 
     TASK [Output mount facts grouped by device name] ******************************************
@@ -79,7 +122,7 @@ This produces:
                 "options": "rw,relatime",
                 "size_available": 42143,
                 "size_total": 543210,
-                "uuid": "bdf50b7d-4859-40af-8665-c637ee7a7808"
+                "uuid": "abcdef01-2345-6789-0abc-def012345678"
             },
             "/boot": {
                 "block_available": 2000,

docs/docsite/rst/filter_guide_abstract_informations_lists_helper.rst

@@ -21,6 +21,34 @@ These filters preserve the item order, eliminate duplicates and are an extended
 
 Let us use the lists below 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
 
   A: [9, 5, 7, 1, 9, 4, 10, 5, 9, 7]
@@ -35,9 +63,22 @@ The union of ``A`` and ``B`` can be written as:
 
 This statement produces:
 
+.. ansible-output-data::
+
+    playbook: ~
+
 .. code-block:: yaml
 
-  result: [9, 5, 7, 1, 4, 10, 2, 8, 3]
+  result:
+    - 9
+    - 5
+    - 7
+    - 1
+    - 4
+    - 10
+    - 2
+    - 8
+    - 3
 
 If you want to calculate the intersection of ``A``, ``B`` and ``C``, you can use the following statement:
 
@@ -59,9 +100,14 @@ or
 
 All three statements are equivalent and give:
 
+.. ansible-output-data::
+
+    playbook: ~
+
 .. code-block:: yaml
 
-  result: [1]
+  result:
+    - 1
 
 .. note:: Be aware that in most cases, filter calls without any argument require ``flatten=true``, otherwise the input is returned as result. The reason for this is, that the input is considered as a variable argument and is wrapped by an additional outer list. ``flatten=true`` ensures that this list is removed before the input is processed by the filter logic.
 
@@ -75,7 +121,14 @@ For example, the symmetric difference of ``A``, ``B`` and ``C`` may be written a
 
 This gives:
 
+.. ansible-output-data::
+
+    playbook: ~
+
 .. code-block:: yaml
 
-  result: [5, 8, 3, 1]
-
+  result:
+    - 5
+    - 8
+    - 3
+    - 1

docs/docsite/rst/filter_guide_abstract_informations_merging_lists_of_dictionaries.rst

@@ -12,6 +12,34 @@ If you have two or more lists of dictionaries and want to combine them into a li
 
 Let us use the lists below 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: list3
+
 .. code-block:: yaml
 
   list1:
@@ -34,13 +62,22 @@ In the example below the lists are merged by the attribute ``name``:
 
 This produces:
 
+.. ansible-output-data::
+
+    playbook: ~
+
 .. code-block:: yaml
 
   list3:
-    - {name: bar, extra: false}
-    - {name: baz, path: /baz}
-    - {name: foo, extra: true, path: /foo}
-    - {name: meh, extra: true}
+    - extra: false
+      name: bar
+    - name: baz
+      path: /baz
+    - extra: true
+      name: foo
+      path: /foo
+    - extra: true
+      name: meh
 
 
 .. versionadded:: 2.0.0
@@ -56,13 +93,22 @@ It is possible to use a list of lists as an input of the filter:
 
 This produces the same result as in the previous example:
 
+.. ansible-output-data::
+
+    playbook: ~
+
 .. code-block:: yaml
 
   list3:
-    - {name: bar, extra: false}
-    - {name: baz, path: /baz}
-    - {name: foo, extra: true, path: /foo}
-    - {name: meh, extra: true}
+    - extra: false
+      name: bar
+    - name: baz
+      path: /baz
+    - extra: true
+      name: foo
+      path: /foo
+    - extra: true
+      name: meh
 
 Single list
 """""""""""
@@ -75,13 +121,22 @@ It is possible to merge single list:
 
 This produces the same result as in the previous example:
 
+.. ansible-output-data::
+
+    playbook: ~
+
 .. code-block:: yaml
 
   list3:
-    - {name: bar, extra: false}
-    - {name: baz, path: /baz}
-    - {name: foo, extra: true, path: /foo}
-    - {name: meh, extra: true}
+    - extra: false
+      name: bar
+    - name: baz
+      path: /baz
+    - extra: true
+      name: foo
+      path: /foo
+    - extra: true
+      name: meh
 
 
 The filter also accepts two optional parameters: :ansopt:`community.general.lists_mergeby#filter:recursive` and :ansopt:`community.general.lists_mergeby#filter:list_merge`. This is available since community.general 4.4.0.
@@ -96,6 +151,11 @@ The examples below set :ansopt:`community.general.lists_mergeby#filter:recursive
 
 Let us use the lists below in the following examples
 
+.. ansible-output-meta::
+
+  actions:
+    - name: reset-previous-blocks
+
 .. code-block:: yaml
 
   list1:
@@ -128,17 +188,25 @@ Example :ansopt:`community.general.lists_mergeby#filter:list_merge=replace` (def
 
 This produces:
 
+.. ansible-output-data::
+
+    playbook: ~
+
 .. code-block:: yaml
 
   list3:
     - name: myname01
       param01:
+        list:
+          - patch_value
         x: default_value
         y: patch_value
-        list: [patch_value]
         z: patch_value
     - name: myname02
-      param01: [3, 4, 4]
+      param01:
+        - 3
+        - 4
+        - 4
 
 list_merge=keep
 """""""""""""""
@@ -153,17 +221,26 @@ Example :ansopt:`community.general.lists_mergeby#filter:list_merge=keep`:
 
 This produces:
 
+.. ansible-output-data::
+
+    playbook: ~
+
 .. code-block:: yaml
 
   list3:
     - name: myname01
       param01:
+        list:
+          - default_value
         x: default_value
         y: patch_value
-        list: [default_value]
         z: patch_value
     - name: myname02
-      param01: [1, 1, 2, 3]
+      param01:
+        - 1
+        - 1
+        - 2
+        - 3
 
 list_merge=append
 """""""""""""""""
@@ -178,17 +255,30 @@ Example :ansopt:`community.general.lists_mergeby#filter:list_merge=append`:
 
 This produces:
 
+.. ansible-output-data::
+
+    playbook: ~
+
 .. code-block:: yaml
 
   list3:
     - name: myname01
       param01:
+        list:
+          - default_value
+          - patch_value
         x: default_value
         y: patch_value
-        list: [default_value, patch_value]
         z: patch_value
     - name: myname02
-      param01: [1, 1, 2, 3, 3, 4, 4]
+      param01:
+        - 1
+        - 1
+        - 2
+        - 3
+        - 3
+        - 4
+        - 4
 
 list_merge=prepend
 """"""""""""""""""
@@ -203,17 +293,30 @@ Example :ansopt:`community.general.lists_mergeby#filter:list_merge=prepend`:
 
 This produces:
 
+.. ansible-output-data::
+
+    playbook: ~
+
 .. code-block:: yaml
 
   list3:
     - name: myname01
       param01:
+        list:
+          - patch_value
+          - default_value
         x: default_value
         y: patch_value
-        list: [patch_value, default_value]
         z: patch_value
     - name: myname02
-      param01: [3, 4, 4, 1, 1, 2, 3]
+      param01:
+        - 3
+        - 4
+        - 4
+        - 1
+        - 1
+        - 2
+        - 3
 
 list_merge=append_rp
 """"""""""""""""""""
@@ -228,17 +331,29 @@ Example :ansopt:`community.general.lists_mergeby#filter:list_merge=append_rp`:
 
 This produces:
 
+.. ansible-output-data::
+
+    playbook: ~
+
 .. code-block:: yaml
 
   list3:
     - name: myname01
       param01:
+        list:
+          - default_value
+          - patch_value
         x: default_value
         y: patch_value
-        list: [default_value, patch_value]
         z: patch_value
     - name: myname02
-      param01: [1, 1, 2, 3, 4, 4]
+      param01:
+        - 1
+        - 1
+        - 2
+        - 3
+        - 4
+        - 4
 
 list_merge=prepend_rp
 """""""""""""""""""""
@@ -253,15 +368,26 @@ Example :ansopt:`community.general.lists_mergeby#filter:list_merge=prepend_rp`:
 
 This produces:
 
+.. ansible-output-data::
+
+    playbook: ~
+
 .. code-block:: yaml
 
   list3:
     - name: myname01
       param01:
+        list:
+          - patch_value
+          - default_value
         x: default_value
         y: patch_value
-        list: [patch_value, default_value]
         z: patch_value
     - name: myname02
-      param01: [3, 4, 4, 1, 1, 2]
-
+      param01:
+        - 3
+        - 4
+        - 4
+        - 1
+        - 1
+        - 2

docs/docsite/rst/filter_guide_conversions.rst

@@ -24,6 +24,17 @@ Ansible offers the :ansplugin:`community.general.read_csv module <community.gene
 
 This produces:
 
+.. ansible-output-data::
+
+    variables:
+      task:
+        previous_code_block: yaml+jinja
+    playbook: |-
+      - hosts: localhost
+        gather_facts: false
+        tasks:
+          @{{ task | indent(4) }}@
+
 .. code-block:: ansible-output
 
     TASK [Parse CSV from string] **************************************************************
@@ -69,6 +80,34 @@ Converting to JSON
 
 This produces:
 
+.. ansible-output-data::
+
+    skip_first_lines: 3
+    playbook: |-
+      - hosts: localhost
+        gather_facts: false
+        tasks:
+          - ansible.builtin.set_fact:
+              result_stdout: |-
+                bin
+                boot
+                dev
+                etc
+                home
+                lib
+                proc
+                root
+                run
+                tmp
+
+          - name: Run 'ls' to list files in /
+            command: ls /
+            register: result
+
+          - name: Parse the ls output
+            debug:
+              msg: "{{ result_stdout | community.general.jc('ls') }}"
+
 .. code-block:: ansible-output
 
     TASK [Run 'ls' to list files in /] ********************************************************

docs/docsite/rst/filter_guide_creating_identifiers.rst

@@ -25,6 +25,17 @@ Hashids
 
 This produces:
 
+.. ansible-output-data::
+
+    variables:
+      task:
+        previous_code_block: yaml+jinja
+    playbook: |-
+      - hosts: localhost
+        gather_facts: false
+        tasks:
+          @{{ task | indent(4) }}@
+
 .. code-block:: ansible-output
 
     TASK [Create hashid] **********************************************************************
@@ -66,16 +77,32 @@ You can use the :ansplugin:`community.general.random_mac filter <community.gener
 
 This produces:
 
+.. ansible-output-data::
+
+    playbook: |-
+      - hosts: localhost
+        gather_facts: false
+        tasks:
+          - name: "Create a random MAC starting with ff:"
+            debug:
+              # We're using a seed here to avoid randomness in the output
+              msg: "{{ 'FF' | community.general.random_mac(seed='') }}"
+
+          - name: "Create a random MAC starting with 00:11:22:"
+            debug:
+              # We're using a seed here to avoid randomness in the output
+              msg: "{{ '00:11:22' | community.general.random_mac(seed='') }}"
+
 .. code-block:: ansible-output
 
     TASK [Create a random MAC starting with ff:] **********************************************
     ok: [localhost] => {
-        "msg": "ff:69:d3:78:7f:b4"
+        "msg": "ff:84:f5:d1:59:20"
     }
 
     TASK [Create a random MAC starting with 00:11:22:] ****************************************
     ok: [localhost] => {
-        "msg": "00:11:22:71:5d:3b"
+        "msg": "00:11:22:84:f5:d1"
     }
 
 You can also initialize the random number generator from a seed to create random-but-idempotent MAC addresses:

docs/docsite/rst/filter_guide_working_with_times.rst

@@ -69,21 +69,32 @@ Note that months and years are using a simplified representation: a month is 30
 
 This produces:
 
+.. ansible-output-data::
+
+    variables:
+      task:
+        previous_code_block: yaml+jinja
+    playbook: |-
+      - hosts: localhost
+        gather_facts: false
+        tasks:
+          @{{ task | indent(4) }}@
+
 .. code-block:: ansible-output
 
     TASK [Convert string to seconds] **********************************************************
     ok: [localhost] => {
-        "msg": "109210.123"
+        "msg": 109210.123
     }
 
     TASK [Convert string to hours] ************************************************************
     ok: [localhost] => {
-        "msg": "30.336145277778"
+        "msg": 30.336145277778
     }
 
     TASK [Convert string to years (using 365.25 days == 1 year)] ******************************
     ok: [localhost] => {
-        "msg": "1.096851471595"
+        "msg": 1.096851471595
     }
 
 .. versionadded: 0.2.0

docs/docsite/rst/filter_guide_working_with_unicode.rst

@@ -21,9 +21,20 @@ You can use the :ansplugin:`community.general.unicode_normalize filter <communit
 
 This produces:
 
+.. ansible-output-data::
+
+    variables:
+      task:
+        previous_code_block: yaml+jinja
+    playbook: |-
+      - hosts: localhost
+        gather_facts: false
+        tasks:
+          @{{ task | indent(4) }}@
+
 .. code-block:: ansible-output
 
-    TASK [Compare Unicode representations] ********************************************************
+    TASK [Compare Unicode representations] ****************************************************
     ok: [localhost] => {
         "msg": true
     }

docs/docsite/rst/filter_guide_working_with_versions.rst

@@ -23,6 +23,17 @@ If you need to sort a list of version numbers, the Jinja ``sort`` filter is prob
 
 This produces:
 
+.. ansible-output-data::
+
+    variables:
+      task:
+        previous_code_block: yaml+jinja
+    playbook: |-
+      - hosts: localhost
+        gather_facts: false
+        tasks:
+          @{{ task | indent(4) }}@
+
 .. code-block:: ansible-output
 
     TASK [Sort list by version number] ********************************************************

docs/docsite/rst/guide_iocage.rst

@@ -3,11 +3,13 @@
   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
 
-{% for i in examples %}
-{{ i.description }}
+.. _ansible_collections.community.general.docsite.guide_iocage:
 
-.. code-block:: {{ i.lang }}
+************
+Iocage Guide
+************
 
-  {{ lookup('file', i.file) | split('\n') | reject('match', '^(#|---)') | join ('\n') | indent(2) }}
+.. toctree::
+   :maxdepth: 1
 
-{% endfor %}
+   guide_iocage_inventory

docs/docsite/rst/guide_iocage_inventory.rst

@@ -0,0 +1,31 @@
+..
+  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
+
+.. _ansible_collections.community.general.docsite.guide_iocage.guide_iocage_inventory:
+
+community.general.iocage inventory plugin
+=========================================
+
+The inventory plugin :ansplugin:`community.general.iocage#inventory` gets the inventory hosts from the iocage jail manager.
+
+See:
+
+* `iocage - A FreeBSD Jail Manager <https://iocage.readthedocs.io/en/latest>`_
+* `man iocage <https://man.freebsd.org/cgi/man.cgi?query=iocage>`_
+* `Jails and Containers <https://docs.freebsd.org/en/books/handbook/jails>`_
+
+.. note::
+  The output of the examples is YAML formatted. See the option :ansopt:`ansible.builtin.default#callback:result_format`.
+
+.. toctree::
+   :caption: Table of Contents
+   :maxdepth: 1
+
+   guide_iocage_inventory_basics
+   guide_iocage_inventory_dhcp
+   guide_iocage_inventory_hooks
+   guide_iocage_inventory_properties
+   guide_iocage_inventory_tags
+   guide_iocage_inventory_aliases

docs/docsite/rst/guide_iocage_inventory_aliases.rst

@@ -0,0 +1,200 @@
+..
+  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
+
+.. _ansible_collections.community.general.docsite.guide_iocage.guide_iocage_inventory.guide_iocage_inventory_aliases:
+
+Aliases
+-------
+
+Quoting :ref:`inventory_aliases`:
+
+   The ``inventory_hostname`` is the unique identifier for a host in Ansible, this can be an IP or a hostname, but also just an 'alias' or short name for the host.
+
+As root at the iocage host, stop and destroy all jails:
+
+.. code-block:: console
+
+   shell> iocage stop ALL
+   * Stopping srv_1
+     + Executing prestop OK
+     + Stopping services OK
+     + Tearing down VNET OK
+     + Removing devfs_ruleset: 1000 OK
+     + Removing jail process OK
+     + Executing poststop OK
+   * Stopping srv_2
+     + Executing prestop OK
+     + Stopping services OK
+     + Tearing down VNET OK
+     + Removing devfs_ruleset: 1001 OK
+     + Removing jail process OK
+     + Executing poststop OK
+   * Stopping srv_3
+     + Executing prestop OK
+     + Stopping services OK
+     + Tearing down VNET OK
+     + Removing devfs_ruleset: 1002 OK
+     + Removing jail process OK
+     + Executing poststop OK
+   ansible_client is not running!
+
+   shell> iocage destroy -f srv_1 srv_2 srv_3
+   Destroying srv_1
+   Destroying srv_2
+   Destroying srv_3
+
+Create three VNET jails with a DHCP interface from the template *ansible_client*. Use the option ``--count``:
+
+.. code-block:: console
+
+   shell> iocage create --short --template ansible_client --count 3 bpf=1 dhcp=1 vnet=1
+   1c11de2d successfully created!
+   9d94cc9e successfully created!
+   052b9557 successfully created!
+
+The names are random. Start the jails:
+
+.. code-block:: console
+
+   shell> iocage start ALL
+   No default gateway found for ipv6.
+   * Starting 052b9557
+     + Started OK
+     + Using devfs_ruleset: 1000 (iocage generated default)
+     + Configuring VNET OK
+     + Using IP options: vnet
+     + Starting services OK
+     + Executing poststart OK
+     + DHCP Address: 10.1.0.137/24
+   No default gateway found for ipv6.
+   * Starting 1c11de2d
+     + Started OK
+     + Using devfs_ruleset: 1001 (iocage generated default)
+     + Configuring VNET OK
+     + Using IP options: vnet
+     + Starting services OK
+     + Executing poststart OK
+     + DHCP Address: 10.1.0.146/24
+   No default gateway found for ipv6.
+   * Starting 9d94cc9e
+     + Started OK
+     + Using devfs_ruleset: 1002 (iocage generated default)
+     + Configuring VNET OK
+     + Using IP options: vnet
+     + Starting services OK
+     + Executing poststart OK
+     + DHCP Address: 10.1.0.115/24
+   Please convert back to a jail before trying to start ansible_client
+
+List the jails:
+
+.. code-block:: console
+
+   shell> iocage list -l
+   +-----+----------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+   | JID |   NAME   | BOOT | STATE | TYPE |     RELEASE     |        IP4         | IP6 |    TEMPLATE    | BASEJAIL |
+   +=====+==========+======+=======+======+=================+====================+=====+================+==========+
+   | 207 | 052b9557 | off  | up    | jail | 14.2-RELEASE-p3 | epair0b|10.1.0.137 | -   | ansible_client | no       |
+   +-----+----------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+   | 208 | 1c11de2d | off  | up    | jail | 14.2-RELEASE-p3 | epair0b|10.1.0.146 | -   | ansible_client | no       |
+   +-----+----------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+   | 209 | 9d94cc9e | off  | up    | jail | 14.2-RELEASE-p3 | epair0b|10.1.0.115 | -   | ansible_client | no       |
+   +-----+----------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+
+Set notes. The tag *alias* will be used to create inventory aliases:
+
+.. code-block:: console
+
+   shell> iocage set notes="vmm=iocage_02 project=foo alias=srv_1" 052b9557
+   notes: none -> vmm=iocage_02 project=foo alias=srv_1
+   shell> iocage set notes="vmm=iocage_02 project=foo alias=srv_2" 1c11de2d
+   notes: none -> vmm=iocage_02 project=foo alias=srv_2
+   shell> iocage set notes="vmm=iocage_02 project=bar alias=srv_3" 9d94cc9e
+   notes: none -> vmm=iocage_02 project=bar alias=srv_3
+
+Update the inventory configuration. Set the option
+:ansopt:`community.general.iocage#inventory:inventory_hostname_tag` to :ansval:`alias`. This tag keeps the
+value of the alias. The option :ansopt:`community.general.iocage#inventory:get_properties` must be
+enabled. For example, ``hosts/02_iocage.yml`` contains:
+
+.. code-block:: yaml
+
+   plugin: community.general.iocage
+   host: 10.1.0.73
+   user: admin
+   get_properties: true
+   inventory_hostname_tag: alias
+   hooks_results:
+     - /var/db/dhclient-hook.address.epair0b
+   compose:
+     ansible_host: (iocage_hooks.0 == '-') | ternary(iocage_ip4, iocage_hooks.0)
+     iocage_tags: dict(iocage_properties.notes | split | map('split', '='))
+   keyed_groups:
+     - prefix: vmm
+       key: iocage_tags.vmm
+     - prefix: project
+       key: iocage_tags.project
+
+Display tags and groups. Create a playbook ``pb-test-groups.yml`` with the following content:
+
+.. code-block:: yaml+jinja
+
+   - hosts: all
+     remote_user: admin
+
+     vars:
+
+       ansible_python_interpreter: auto_silent
+
+     tasks:
+
+       - debug:
+           var: iocage_tags
+
+       - debug:
+           msg: |
+             {% for group in groups %}
+             {{ group }}: {{ groups[group] }}
+             {% endfor %}
+         run_once: true
+
+Run the playbook:
+
+.. code-block:: console
+
+   shell> ansible-playbook -i hosts/02_iocage.yml pb-test-groups.yml
+
+   PLAY [all] **********************************************************************************************************
+
+   TASK [debug] ********************************************************************************************************
+   ok: [srv_1] =>
+       iocage_tags:
+           alias: srv_1
+           project: foo
+           vmm: iocage_02
+   ok: [srv_2] =>
+       iocage_tags:
+           alias: srv_2
+           project: foo
+           vmm: iocage_02
+   ok: [srv_3] =>
+       iocage_tags:
+           alias: srv_3
+           project: bar
+           vmm: iocage_02
+
+   TASK [debug] ********************************************************************************************************
+   ok: [srv_1] =>
+       msg: |-
+           all: ['srv_1', 'srv_2', 'srv_3']
+           ungrouped: []
+           vmm_iocage_02: ['srv_1', 'srv_2', 'srv_3']
+           project_foo: ['srv_1', 'srv_2']
+           project_bar: ['srv_3']
+
+   PLAY RECAP **********************************************************************************************************
+   srv_1                      : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
+   srv_2                      : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
+   srv_3                      : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

docs/docsite/rst/guide_iocage_inventory_basics.rst

@@ -0,0 +1,128 @@
+..
+  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
+
+.. _ansible_collections.community.general.docsite.guide_iocage.guide_iocage_inventory.guide_iocage_inventory_basics:
+
+Basics
+------
+
+As root at the iocage host, create three VNET jails with a DHCP interface from the template
+*ansible_client*:
+
+.. code-block:: console
+
+   shell> iocage create --template ansible_client --name srv_1 bpf=1 dhcp=1 vnet=1
+   srv_1 successfully created!
+   shell> iocage create --template ansible_client --name srv_2 bpf=1 dhcp=1 vnet=1
+   srv_2 successfully created!
+   shell> iocage create --template ansible_client --name srv_3 bpf=1 dhcp=1 vnet=1
+   srv_3 successfully created!
+
+See: `Configuring a VNET Jail <https://iocage.readthedocs.io/en/latest/networking.html#configuring-a-vnet-jail>`_.
+
+As admin at the controller, list the jails:
+
+.. code-block:: console
+
+   shell> ssh admin@10.1.0.73 iocage list -l
+   +------+-------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+   | JID  | NAME  | BOOT | STATE | TYPE |     RELEASE     |        IP4         | IP6 |    TEMPLATE    | BASEJAIL |
+   +======+=======+======+=======+======+=================+====================+=====+================+==========+
+   | None | srv_1 | off  | down  | jail | 14.2-RELEASE-p3 | DHCP (not running) | -   | ansible_client | no       |
+   +------+-------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+   | None | srv_2 | off  | down  | jail | 14.2-RELEASE-p3 | DHCP (not running) | -   | ansible_client | no       |
+   +------+-------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+   | None | srv_3 | off  | down  | jail | 14.2-RELEASE-p3 | DHCP (not running) | -   | ansible_client | no       |
+   +------+-------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+
+Create the inventory file ``hosts/02_iocage.yml``
+
+.. code-block:: yaml
+
+   plugin: community.general.iocage
+   host: 10.1.0.73
+   user: admin
+
+Display the inventory:
+
+.. code-block:: console
+
+   shell> ansible-inventory -i hosts/02_iocage.yml --list --yaml
+   all:
+     children:
+       ungrouped:
+         hosts:
+           srv_1:
+             iocage_basejail: 'no'
+             iocage_boot: 'off'
+             iocage_ip4: '-'
+             iocage_ip4_dict:
+               ip4: []
+               msg: DHCP (not running)
+             iocage_ip6: '-'
+             iocage_jid: None
+             iocage_release: 14.2-RELEASE-p3
+             iocage_state: down
+             iocage_template: ansible_client
+             iocage_type: jail
+           srv_2:
+             iocage_basejail: 'no'
+             iocage_boot: 'off'
+             iocage_ip4: '-'
+             iocage_ip4_dict:
+               ip4: []
+               msg: DHCP (not running)
+             iocage_ip6: '-'
+             iocage_jid: None
+             iocage_release: 14.2-RELEASE-p3
+             iocage_state: down
+             iocage_template: ansible_client
+             iocage_type: jail
+           srv_3:
+             iocage_basejail: 'no'
+             iocage_boot: 'off'
+             iocage_ip4: '-'
+             iocage_ip4_dict:
+               ip4: []
+               msg: DHCP (not running)
+             iocage_ip6: '-'
+             iocage_jid: None
+             iocage_release: 14.2-RELEASE-p3
+             iocage_state: down
+             iocage_template: ansible_client
+             iocage_type: jail
+
+Optionally, create shared IP jails:
+
+.. code-block:: console
+
+   shell> iocage create --template ansible_client --name srv_1 ip4_addr="em0|10.1.0.101/24"
+   srv_1 successfully created!
+   shell> iocage create --template ansible_client --name srv_2 ip4_addr="em0|10.1.0.102/24"
+   srv_2 successfully created!
+   shell> iocage create --template ansible_client --name srv_3 ip4_addr="em0|10.1.0.103/24"
+   srv_3 successfully created!
+   shell> iocage list -l
+   +------+-------+------+-------+------+-----------------+-------------------+-----+----------------+----------+
+   | JID  | NAME  | BOOT | STATE | TYPE |     RELEASE     |        IP4        | IP6 |    TEMPLATE    | BASEJAIL |
+   +======+=======+======+=======+======+=================+===================+=====+================+==========+
+   | None | srv_1 | off  | down  | jail | 14.2-RELEASE-p3 | em0|10.1.0.101/24 | -   | ansible_client | no       |
+   +------+-------+------+-------+------+-----------------+-------------------+-----+----------------+----------+
+   | None | srv_2 | off  | down  | jail | 14.2-RELEASE-p3 | em0|10.1.0.102/24 | -   | ansible_client | no       |
+   +------+-------+------+-------+------+-----------------+-------------------+-----+----------------+----------+
+   | None | srv_3 | off  | down  | jail | 14.2-RELEASE-p3 | em0|10.1.0.103/24 | -   | ansible_client | no       |
+   +------+-------+------+-------+------+-----------------+-------------------+-----+----------------+----------+
+
+See: `Configuring a Shared IP Jail <https://iocage.readthedocs.io/en/latest/networking.html#configuring-a-shared-ip-jail>`_
+
+If iocage needs environment variable(s), use the option :ansopt:`community.general.iocage#inventory:env`. For example,
+
+.. code-block:: yaml
+
+   plugin: community.general.iocage
+   host: 10.1.0.73
+   user: admin
+   env:
+     CRYPTOGRAPHY_OPENSSL_NO_LEGACY: 1

docs/docsite/rst/guide_iocage_inventory_dhcp.rst

@@ -0,0 +1,175 @@
+..
+  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
+
+.. _ansible_collections.community.general.docsite.guide_iocage.guide_iocage_inventory.guide_iocage_inventory_dhcp:
+
+DHCP
+----
+
+As root at the iocage host, start the jails:
+
+.. code-block:: console
+
+   shell> iocage start ALL
+   No default gateway found for ipv6.
+   * Starting srv_1
+     + Started OK
+     + Using devfs_ruleset: 1000 (iocage generated default)
+     + Configuring VNET OK
+     + Using IP options: vnet
+     + Starting services OK
+     + Executing poststart OK
+     + DHCP Address: 10.1.0.183/24
+   No default gateway found for ipv6.
+   * Starting srv_2
+     + Started OK
+     + Using devfs_ruleset: 1001 (iocage generated default)
+     + Configuring VNET OK
+     + Using IP options: vnet
+     + Starting services OK
+     + Executing poststart OK
+     + DHCP Address: 10.1.0.204/24
+   No default gateway found for ipv6.
+   * Starting srv_3
+     + Started OK
+     + Using devfs_ruleset: 1002 (iocage generated default)
+     + Configuring VNET OK
+     + Using IP options: vnet
+     + Starting services OK
+     + Executing poststart OK
+     + DHCP Address: 10.1.0.169/24
+   Please convert back to a jail before trying to start ansible_client
+
+List the jails:
+
+.. code-block:: console
+
+   shell> iocage list -l
+   +-----+-------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+   | JID | NAME  | BOOT | STATE | TYPE |     RELEASE     |        IP4         | IP6 |    TEMPLATE    | BASEJAIL |
+   +=====+=======+======+=======+======+=================+====================+=====+================+==========+
+   | 204 | srv_1 | off  | up    | jail | 14.2-RELEASE-p3 | epair0b|10.1.0.183 | -   | ansible_client | no       |
+   +-----+-------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+   | 205 | srv_2 | off  | up    | jail | 14.2-RELEASE-p3 | epair0b|10.1.0.204 | -   | ansible_client | no       |
+   +-----+-------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+   | 206 | srv_3 | off  | up    | jail | 14.2-RELEASE-p3 | epair0b|10.1.0.169 | -   | ansible_client | no       |
+   +-----+-------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+
+As admin at the controller, list the jails. The IP4 tab says "... address requires root":
+
+.. code-block:: console
+
+   shell> ssh admin@10.1.0.73 iocage list -l
+   +-----+-------+------+-------+------+-----------------+-----------------------------------------+-----+----------------+----------+
+   | JID | NAME  | BOOT | STATE | TYPE |     RELEASE     |                   IP4                   | IP6 |    TEMPLATE    | BASEJAIL |
+   +=====+=======+======+=======+======+=================+=========================================+=====+================+==========+
+   | 204 | srv_1 | off  | up    | jail | 14.2-RELEASE-p3 | DHCP (running -- address requires root) | -   | ansible_client | no       |
+   +-----+-------+------+-------+------+-----------------+-----------------------------------------+-----+----------------+----------+
+   | 205 | srv_2 | off  | up    | jail | 14.2-RELEASE-p3 | DHCP (running -- address requires root) | -   | ansible_client | no       |
+   +-----+-------+------+-------+------+-----------------+-----------------------------------------+-----+----------------+----------+
+   | 206 | srv_3 | off  | up    | jail | 14.2-RELEASE-p3 | DHCP (running -- address requires root) | -   | ansible_client | no       |
+   +-----+-------+------+-------+------+-----------------+-----------------------------------------+-----+----------------+----------+
+
+Use sudo if enabled:
+
+.. code-block:: console
+
+   shell> ssh admin@10.1.0.73 sudo iocage list -l
+   +-----+-------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+   | JID | NAME  | BOOT | STATE | TYPE |     RELEASE     |        IP4         | IP6 |    TEMPLATE    | BASEJAIL |
+   +=====+=======+======+=======+======+=================+====================+=====+================+==========+
+   | 204 | srv_1 | off  | up    | jail | 14.2-RELEASE-p3 | epair0b|10.1.0.183 | -   | ansible_client | no       |
+   +-----+-------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+   | 205 | srv_2 | off  | up    | jail | 14.2-RELEASE-p3 | epair0b|10.1.0.204 | -   | ansible_client | no       |
+   +-----+-------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+   | 206 | srv_3 | off  | up    | jail | 14.2-RELEASE-p3 | epair0b|10.1.0.169 | -   | ansible_client | no       |
+   +-----+-------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
+
+Create the inventory file ``hosts/02_iocage.yml``. Use the option
+:ansopt:`community.general.iocage#inventory:sudo`:
+
+.. code-block:: yaml
+
+   plugin: community.general.iocage
+   host: 10.1.0.73
+   user: admin
+   sudo: true
+
+Display the inventory:
+
+.. code-block:: console
+
+   shell> ansible-inventory -i hosts/02_iocage.yml --list --yaml
+   all:
+     children:
+       ungrouped:
+         hosts:
+           srv_1:
+             iocage_basejail: 'no'
+             iocage_boot: 'off'
+             iocage_ip4: 10.1.0.183
+             iocage_ip4_dict:
+               ip4:
+               - ifc: epair0b
+                 ip: 10.1.0.183
+                 mask: '-'
+               msg: ''
+             iocage_ip6: '-'
+             iocage_jid: '204'
+             iocage_release: 14.2-RELEASE-p3
+             iocage_state: up
+             iocage_template: ansible_client
+             iocage_type: jail
+           srv_2:
+             iocage_basejail: 'no'
+             iocage_boot: 'off'
+             iocage_ip4: 10.1.0.204
+             iocage_ip4_dict:
+               ip4:
+               - ifc: epair0b
+                 ip: 10.1.0.204
+                 mask: '-'
+               msg: ''
+             iocage_ip6: '-'
+             iocage_jid: '205'
+             iocage_release: 14.2-RELEASE-p3
+             iocage_state: up
+             iocage_template: ansible_client
+             iocage_type: jail
+           srv_3:
+             iocage_basejail: 'no'
+             iocage_boot: 'off'
+             iocage_ip4: 10.1.0.169
+             iocage_ip4_dict:
+               ip4:
+               - ifc: epair0b
+                 ip: 10.1.0.169
+                 mask: '-'
+               msg: ''
+             iocage_ip6: '-'
+             iocage_jid: '206'
+             iocage_release: 14.2-RELEASE-p3
+             iocage_state: up
+             iocage_template: ansible_client
+             iocage_type: jail
+
+Note: If the option :ansopt:`community.general.iocage#inventory:env` is used and :ansopt:`community.general.iocage#inventory:sudo` is enabled, enable also :ansopt:`community.general.iocage#inventory:sudo_preserve_env`. For example,
+
+.. code-block:: yaml
+
+   plugin: community.general.iocage
+   host: 10.1.0.73
+   user: admin
+   env:
+     CRYPTOGRAPHY_OPENSSL_NO_LEGACY: 1
+   sudo: true
+   sudo_preserve_env: true
+
+In this case, make sure the sudo tag ``SETENV`` is used:
+
+.. code-block:: console
+
+   shell> ssh admin@10.1.0.73 sudo cat /usr/local/etc/sudoers | grep admin
+   admin ALL=(ALL) NOPASSWD:SETENV: ALL

docs/docsite/rst/guide_iocage_inventory_hooks.rst

@@ -0,0 +1,187 @@
+..
+  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
+
+.. _ansible_collections.community.general.docsite.guide_iocage.guide_iocage_inventory.guide_iocage_inventory_hooks:
+
+Hooks
+-----
+
+The iocage utility internally opens a console to a jail to get the jail's DHCP address. This
+requires root. If you run the command ``iocage list -l`` as unprivileged user, you'll see the
+message ``DHCP (running -- address requires root)``. If you are not granted the root privilege, use
+``/etc/dhclient-exit-hooks``. For example, in the jail *srv_1*, create the file
+``/zroot/iocage/jails/srv_1/root/etc/dhclient-exit-hooks``
+
+.. code-block:: shell
+
+   case "$reason" in
+       "BOUND"|"REBIND"|"REBOOT"|"RENEW")
+       echo $new_ip_address > /var/db/dhclient-hook.address.$interface
+       ;;
+   esac
+
+where ``/zroot/iocage`` is the activated pool.
+
+.. code-block:: console
+
+   shell> zfs list | grep /zroot/iocage
+   zroot/iocage                                4.69G   446G  5.08M  /zroot/iocage
+   zroot/iocage/download                        927M   446G   384K  /zroot/iocage/download
+   zroot/iocage/download/14.1-RELEASE           465M   446G   465M  /zroot/iocage/download/14.1-RELEASE
+   zroot/iocage/download/14.2-RELEASE           462M   446G   462M  /zroot/iocage/download/14.2-RELEASE
+   zroot/iocage/images                          384K   446G   384K  /zroot/iocage/images
+   zroot/iocage/jails                           189M   446G   480K  /zroot/iocage/jails
+   zroot/iocage/jails/srv_1                    62.9M   446G   464K  /zroot/iocage/jails/srv_1
+   zroot/iocage/jails/srv_1/root               62.4M   446G  3.53G  /zroot/iocage/jails/srv_1/root
+   zroot/iocage/jails/srv_2                    62.8M   446G   464K  /zroot/iocage/jails/srv_2
+   zroot/iocage/jails/srv_2/root               62.3M   446G  3.53G  /zroot/iocage/jails/srv_2/root
+   zroot/iocage/jails/srv_3                    62.8M   446G   464K  /zroot/iocage/jails/srv_3
+   zroot/iocage/jails/srv_3/root               62.3M   446G  3.53G  /zroot/iocage/jails/srv_3/root
+   zroot/iocage/log                             688K   446G   688K  /zroot/iocage/log
+   zroot/iocage/releases                       2.93G   446G   384K  /zroot/iocage/releases
+   zroot/iocage/releases/14.2-RELEASE          2.93G   446G   384K  /zroot/iocage/releases/14.2-RELEASE
+   zroot/iocage/releases/14.2-RELEASE/root     2.93G   446G  2.88G  /zroot/iocage/releases/14.2-RELEASE/root
+   zroot/iocage/templates                       682M   446G   416K  /zroot/iocage/templates
+   zroot/iocage/templates/ansible_client        681M   446G   432K  /zroot/iocage/templates/ansible_client
+   zroot/iocage/templates/ansible_client/root   681M   446G  3.53G  /zroot/iocage/templates/ansible_client/root
+
+See: `man dhclient-script <https://man.freebsd.org/cgi/man.cgi?dhclient-script>`_
+
+Create the inventory configuration. Use the option :ansopt:`community.general.iocage#inventory:hooks_results` instead of :ansopt:`community.general.iocage#inventory:sudo`:
+
+.. code-block:: console
+
+   shell> cat hosts/02_iocage.yml
+
+.. code-block:: yaml
+
+   plugin: community.general.iocage
+   host: 10.1.0.73
+   user: admin
+   hooks_results:
+     - /var/db/dhclient-hook.address.epair0b
+
+.. note::
+
+   The option :ansopt:`community.general.iocage#inventory:hooks_results` expects the poolname to be mounted to ``/poolname``. For example, if you
+   activate the pool iocage, this plugin expects to find the :ansopt:`community.general.iocage#inventory:hooks_results` items in the path
+   /iocage/iocage/jails/<name>/root. If you mount the poolname to a different path, the easiest
+   remedy is to create a symlink.
+
+As admin at the controller, display the inventory:
+
+.. code-block:: console
+
+   shell> ansible-inventory -i hosts/02_iocage.yml --list --yaml
+   all:
+     children:
+       ungrouped:
+         hosts:
+           srv_1:
+             iocage_basejail: 'no'
+             iocage_boot: 'off'
+             iocage_hooks:
+             - 10.1.0.183
+             iocage_ip4: '-'
+             iocage_ip4_dict:
+               ip4: []
+               msg: DHCP (running -- address requires root)
+             iocage_ip6: '-'
+             iocage_jid: '204'
+             iocage_release: 14.2-RELEASE-p3
+             iocage_state: up
+             iocage_template: ansible_client
+             iocage_type: jail
+           srv_2:
+             iocage_basejail: 'no'
+             iocage_boot: 'off'
+             iocage_hooks:
+             - 10.1.0.204
+             iocage_ip4: '-'
+             iocage_ip4_dict:
+               ip4: []
+               msg: DHCP (running -- address requires root)
+             iocage_ip6: '-'
+             iocage_jid: '205'
+             iocage_release: 14.2-RELEASE-p3
+             iocage_state: up
+             iocage_template: ansible_client
+             iocage_type: jail
+           srv_3:
+             iocage_basejail: 'no'
+             iocage_boot: 'off'
+             iocage_hooks:
+             - 10.1.0.169
+             iocage_ip4: '-'
+             iocage_ip4_dict:
+               ip4: []
+               msg: DHCP (running -- address requires root)
+             iocage_ip6: '-'
+             iocage_jid: '206'
+             iocage_release: 14.2-RELEASE-p3
+             iocage_state: up
+             iocage_template: ansible_client
+             iocage_type: jail
+
+Compose the variable ``ansible_host``. For example, ``hosts/02_iocage.yml`` could look like:
+
+.. code-block:: yaml+jinja
+
+   plugin: community.general.iocage
+   host: 10.1.0.73
+   user: admin
+   hooks_results:
+     - /var/db/dhclient-hook.address.epair0b
+   compose:
+     ansible_host: (iocage_hooks.0 == '-') | ternary(iocage_ip4, iocage_hooks.0)
+
+Test the jails. Create a playbook ``pb-test-uname.yml``:
+
+.. code-block:: yaml
+
+   - hosts: all
+     remote_user: admin
+
+     vars:
+
+       ansible_python_interpreter: auto_silent
+
+     tasks:
+
+       - command: uname -a
+         register: out
+
+       - debug:
+           var: out.stdout
+
+See: :ref:`working_with_bsd`
+
+Run the playbook:
+
+.. code-block:: console
+
+   shell> ansible-playbook -i hosts/02_iocage.yml pb-test-uname.yml
+
+   PLAY [all] **********************************************************************************************************
+
+   TASK [command] ******************************************************************************************************
+   changed: [srv_3]
+   changed: [srv_1]
+   changed: [srv_2]
+
+   TASK [debug] ********************************************************************************************************
+   ok: [srv_1] =>
+       out.stdout: FreeBSD srv-1 14.2-RELEASE-p1 FreeBSD 14.2-RELEASE-p1 GENERIC amd64
+   ok: [srv_3] =>
+       out.stdout: FreeBSD srv-3 14.2-RELEASE-p1 FreeBSD 14.2-RELEASE-p1 GENERIC amd64
+   ok: [srv_2] =>
+       out.stdout: FreeBSD srv-2 14.2-RELEASE-p1 FreeBSD 14.2-RELEASE-p1 GENERIC amd64
+
+   PLAY RECAP **********************************************************************************************************
+   srv_1                      : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
+   srv_2                      : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
+   srv_3                      : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
+
+Note: This playbook and the inventory configuration works also for the *Shared IP Jails*.

docs/docsite/rst/guide_iocage_inventory_properties.rst

@@ -0,0 +1,201 @@
+..
+  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
+
+.. _ansible_collections.community.general.docsite.guide_iocage.guide_iocage_inventory.guide_iocage_inventory_properties:
+
+Properties
+----------
+
+Optionally, in the inventory file ``hosts/02_iocage.yml``, get the iocage properties. Enable
+:ansopt:`community.general.iocage#inventory:get_properties`:
+
+.. code-block:: yaml+jinja
+
+   plugin: community.general.iocage
+   host: 10.1.0.73
+   user: admin
+   get_properties: true
+   hooks_results:
+     - /var/db/dhclient-hook.address.epair0b
+   compose:
+     ansible_host: (iocage_hooks.0 == '-') | ternary(iocage_ip4, iocage_hooks.0)
+
+Display the properties. Create the playbook ``pb-test-properties.yml``:
+
+.. code-block:: yaml
+
+   - hosts: all
+     remote_user: admin
+
+     vars:
+
+       ansible_python_interpreter: auto_silent
+
+     tasks:
+
+       - debug:
+           var: iocage_properties
+
+Run the playbook. Limit the inventory to *srv_3*:
+
+.. code-block:: console
+
+   shell> ansible-playbook -i hosts/02_iocage.yml -l srv_3 pb-test-properties.yml
+
+   PLAY [all] **********************************************************************************************************
+
+   TASK [debug] ********************************************************************************************************
+   ok: [srv_3] =>
+       iocage_properties:
+           CONFIG_VERSION: '33'
+           allow_chflags: '0'
+           allow_mlock: '0'
+           allow_mount: '1'
+           allow_mount_devfs: '0'
+           allow_mount_fdescfs: '0'
+           allow_mount_fusefs: '0'
+           allow_mount_linprocfs: '0'
+           allow_mount_linsysfs: '0'
+           allow_mount_nullfs: '0'
+           allow_mount_procfs: '0'
+           allow_mount_tmpfs: '0'
+           allow_mount_zfs: '0'
+           allow_nfsd: '0'
+           allow_quotas: '0'
+           allow_raw_sockets: '0'
+           allow_set_hostname: '1'
+           allow_socket_af: '0'
+           allow_sysvipc: '0'
+           allow_tun: '0'
+           allow_vmm: '0'
+           assign_localhost: '0'
+           available: readonly
+           basejail: '0'
+           boot: '0'
+           bpf: '1'
+           children_max: '0'
+           cloned_release: 14.2-RELEASE
+           comment: none
+           compression: 'on'
+           compressratio: readonly
+           coredumpsize: 'off'
+           count: '1'
+           cpuset: 'off'
+           cputime: 'off'
+           datasize: 'off'
+           dedup: 'off'
+           defaultrouter: auto
+           defaultrouter6: auto
+           depends: none
+           devfs_ruleset: '4'
+           dhcp: '1'
+           enforce_statfs: '2'
+           exec_clean: '1'
+           exec_created: /usr/bin/true
+           exec_fib: '0'
+           exec_jail_user: root
+           exec_poststart: /usr/bin/true
+           exec_poststop: /usr/bin/true
+           exec_prestart: /usr/bin/true
+           exec_prestop: /usr/bin/true
+           exec_start: /bin/sh /etc/rc
+           exec_stop: /bin/sh /etc/rc.shutdown
+           exec_system_jail_user: '0'
+           exec_system_user: root
+           exec_timeout: '60'
+           host_domainname: none
+           host_hostname: srv-3
+           host_hostuuid: srv_3
+           host_time: '1'
+           hostid: ea2ba7d1-4fcd-f13f-82e4-8b32c0a03403
+           hostid_strict_check: '0'
+           interfaces: vnet0:bridge0
+           ip4: new
+           ip4_addr: none
+           ip4_saddrsel: '1'
+           ip6: new
+           ip6_addr: none
+           ip6_saddrsel: '1'
+           ip_hostname: '0'
+           jail_zfs: '0'
+           jail_zfs_dataset: iocage/jails/srv_3/data
+           jail_zfs_mountpoint: none
+           last_started: '2025-06-11 04:29:23'
+           localhost_ip: none
+           login_flags: -f root
+           mac_prefix: 02a098
+           maxproc: 'off'
+           memorylocked: 'off'
+           memoryuse: 'off'
+           min_dyn_devfs_ruleset: '1000'
+           mount_devfs: '1'
+           mount_fdescfs: '1'
+           mount_linprocfs: '0'
+           mount_procfs: '0'
+           mountpoint: readonly
+           msgqqueued: 'off'
+           msgqsize: 'off'
+           nat: '0'
+           nat_backend: ipfw
+           nat_forwards: none
+           nat_interface: none
+           nat_prefix: '172.16'
+           nmsgq: 'off'
+           notes: none
+           nsem: 'off'
+           nsemop: 'off'
+           nshm: 'off'
+           nthr: 'off'
+           openfiles: 'off'
+           origin: readonly
+           owner: root
+           pcpu: 'off'
+           plugin_name: none
+           plugin_repository: none
+           priority: '99'
+           pseudoterminals: 'off'
+           quota: none
+           readbps: 'off'
+           readiops: 'off'
+           release: 14.2-RELEASE-p3
+           reservation: none
+           resolver: /etc/resolv.conf
+           rlimits: 'off'
+           rtsold: '0'
+           securelevel: '2'
+           shmsize: 'off'
+           source_template: ansible_client
+           stacksize: 'off'
+           state: up
+           stop_timeout: '30'
+           swapuse: 'off'
+           sync_state: none
+           sync_target: none
+           sync_tgt_zpool: none
+           sysvmsg: new
+           sysvsem: new
+           sysvshm: new
+           template: '0'
+           type: jail
+           used: readonly
+           vmemoryuse: 'off'
+           vnet: '1'
+           vnet0_mac: 02a0983da05d 02a0983da05e
+           vnet0_mtu: auto
+           vnet1_mac: none
+           vnet1_mtu: auto
+           vnet2_mac: none
+           vnet2_mtu: auto
+           vnet3_mac: none
+           vnet3_mtu: auto
+           vnet_default_interface: auto
+           vnet_default_mtu: '1500'
+           vnet_interfaces: none
+           wallclock: 'off'
+           writebps: 'off'
+           writeiops: 'off'
+
+   PLAY RECAP **********************************************************************************************************
+   srv_3                      : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

docs/docsite/rst/guide_iocage_inventory_tags.rst

@@ -0,0 +1,117 @@
+..
+  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
+
+.. _ansible_collections.community.general.docsite.guide_iocage.guide_iocage_inventory.guide_iocage_inventory_tags:
+
+Tags
+----
+
+Quoting `man iocage <https://man.freebsd.org/cgi/man.cgi?query=iocage>`_
+
+.. code-block:: text
+
+   PROPERTIES
+   ...
+   notes="any string"
+         Custom notes for miscellaneous tagging.
+         Default: none
+         Source: local
+
+We will use the format ``notes="tag1=value1 tag2=value2 ..."``.
+
+.. note::
+
+    The iocage tags have nothing to do with the :ref:`tags`.
+
+As root at the iocage host, set notes. For example,
+
+.. code-block:: console
+
+   shell> iocage set notes="vmm=iocage_02 project=foo" srv_1
+   notes: none -> vmm=iocage_02 project=foo
+   shell> iocage set notes="vmm=iocage_02 project=foo" srv_2
+   notes: none -> vmm=iocage_02 project=foo
+   shell> iocage set notes="vmm=iocage_02 project=bar" srv_3
+   notes: none -> vmm=iocage_02 project=bar
+
+Update the inventory configuration. Compose a dictionary *iocage_tags* and create groups. The option
+:ansopt:`community.general.iocage#inventory:get_properties` must be enabled.
+For example, ``hosts/02_iocage.yml`` could look like:
+
+.. code-block:: yaml
+
+   plugin: community.general.iocage
+   host: 10.1.0.73
+   user: admin
+   get_properties: true
+   hooks_results:
+     - /var/db/dhclient-hook.address.epair0b
+   compose:
+     ansible_host: (iocage_hooks.0 == '-') | ternary(iocage_ip4, iocage_hooks.0)
+     iocage_tags: dict(iocage_properties.notes | split | map('split', '='))
+   keyed_groups:
+     - prefix: vmm
+       key: iocage_tags.vmm
+     - prefix: project
+       key: iocage_tags.project
+
+Display tags and groups. Create a playbook ``pb-test-groups.yml``:
+
+.. code-block:: yaml+jinja
+
+   - hosts: all
+     remote_user: admin
+
+     vars:
+
+       ansible_python_interpreter: auto_silent
+
+     tasks:
+
+       - debug:
+           var: iocage_tags
+
+       - debug:
+           msg: |
+             {% for group in groups %}
+             {{ group }}: {{ groups[group] }}
+             {% endfor %}
+         run_once: true
+
+Run the playbook:
+
+.. code-block:: console
+
+   shell> ansible-playbook -i hosts/02_iocage.yml pb-test-groups.yml
+
+   PLAY [all] **********************************************************************************************************
+
+   TASK [debug] ********************************************************************************************************
+   ok: [srv_1] =>
+       iocage_tags:
+           project: foo
+           vmm: iocage_02
+   ok: [srv_2] =>
+       iocage_tags:
+           project: foo
+           vmm: iocage_02
+   ok: [srv_3] =>
+       iocage_tags:
+           project: bar
+           vmm: iocage_02
+
+   TASK [debug] ********************************************************************************************************
+   ok: [srv_1] =>
+       msg: |-
+           all: ['srv_1', 'srv_2', 'srv_3']
+           ungrouped: []
+           vmm_iocage_02: ['srv_1', 'srv_2', 'srv_3']
+           project_foo: ['srv_1', 'srv_2']
+           project_bar: ['srv_3']
+
+   PLAY RECAP **********************************************************************************************************
+   srv_1                      : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
+   srv_2                      : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
+   srv_3                      : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

docs/docsite/rst/guide_modulehelper.rst

@@ -38,7 +38,6 @@ But bear in mind that it does not showcase all of MH's features:
             ),
             supports_check_mode=True,
         )
-        use_old_vardict = False
 
         def __run__(self):
             self.vars.original_message = ''
@@ -85,10 +84,6 @@ section above, but there are more elements that will take part in it.
 
         facts_name = None   # used if generating facts, from parameters or otherwise
 
-        # transitional variables for the new VarDict implementation, see information below
-        use_old_vardict = True
-        mute_vardict_deprecation = False
-
         module = dict(
             argument_spec=dict(...),
             # ...
@@ -208,28 +203,14 @@ By using ``self.vars``, you get a central mechanism to access the parameters but
 As described in :ref:`ansible_collections.community.general.docsite.guide_vardict`, variables in ``VarDict`` have metadata associated to them.
 One of the attributes in that metadata marks the variable for output, and MH makes use of that to generate the module's return values.
 
-.. important::
+.. note::
 
-    The ``VarDict`` feature described was introduced in community.general 7.1.0, but there was a first
-    implementation of it embedded within ``ModuleHelper``.
-    That older implementation is now deprecated and will be removed in community.general 11.0.0.
-    After community.general 7.1.0, MH modules generate a deprecation message about *using the old VarDict*.
-    There are two ways to prevent that from happening:
+    The ``VarDict`` class was introduced in community.general 7.1.0, as part of ``ModuleHelper`` itself.
+    However, it has been factored out to become an utility on its own, described in :ref:`ansible_collections.community.general.docsite.guide_vardict`,
+    and the older implementation was removed in community.general 11.0.0.
 
-        #.  Set ``mute_vardict_deprecation = True`` and the deprecation will be silenced. If the module still uses the old ``VarDict``,
-            it will not be able to update to community.general 11.0.0 (Spring 2025) upon its release.
-        #.  Set ``use_old_vardict = False`` to make the MH module use the new ``VarDict`` immediately.
-            We strongly recommend you use the new ``VarDict``, for that you make sure to consult its documentation at
-            :ref:`ansible_collections.community.general.docsite.guide_vardict`.
-
-    .. code-block:: python
-
-        class MyTest(ModuleHelper):
-            use_old_vardict = False
-            mute_vardict_deprecation = True
-            ...
-
-    These two settings are mutually exclusive, but that is not enforced and the behavior when setting both is not specified.
+    Some code might still refer to the class variables ``use_old_vardict`` and ``mute_vardict_deprecation``, used for the transtition to the new
+    implementation but from community.general 11.0.0 onwards they are no longer used and can be safely removed from the code.
 
 Contrary to new variables created in ``VarDict``, module parameters are not set for output by default.
 If you want to include some module parameters in the output, list them in the ``output_params`` class variable.
@@ -411,7 +392,6 @@ By using ``StateModuleHelper`` you can make your code like the excerpt from the
         module = dict(
             ...
         )
-        use_old_vardict = False
 
         def __init_module__(self):
             self.runner = gconftool2_runner(self.module, check_rc=True)