From 29ff1241ce26deb746fd77b56ce13389fe88553d Mon Sep 17 00:00:00 2001
From: Felix Fontein <felix@fontein.de>
Date: Tue, 7 Jan 2025 21:21:01 +0100
Subject: [PATCH] Use multiple YAML documents for inventory plugin examples.
 (#1023)

---
 plugins/inventory/docker_containers.py | 7 +++++++
 plugins/inventory/docker_machine.py    | 7 +++++++
 plugins/inventory/docker_swarm.py      | 5 +++++
 tests/sanity/ignore-2.15.txt           | 3 +++
 tests/sanity/ignore-2.16.txt           | 3 +++
 5 files changed, 25 insertions(+)

diff --git a/plugins/inventory/docker_containers.py b/plugins/inventory/docker_containers.py
index a5b3ac8c..37ba84db 100644
--- a/plugins/inventory/docker_containers.py
+++ b/plugins/inventory/docker_containers.py
@@ -110,19 +110,23 @@ options:
 """
 
 EXAMPLES = '''
+---
 # Minimal example using local Docker daemon
 plugin: community.docker.docker_containers
 docker_host: unix:///var/run/docker.sock
 
+---
 # Minimal example using remote Docker daemon
 plugin: community.docker.docker_containers
 docker_host: tcp://my-docker-host:2375
 
+---
 # Example using remote Docker daemon with unverified TLS
 plugin: community.docker.docker_containers
 docker_host: tcp://my-docker-host:2376
 tls: true
 
+---
 # Example using remote Docker daemon with verified TLS and client certificate verification
 plugin: community.docker.docker_containers
 docker_host: tcp://my-docker-host:2376
@@ -131,6 +135,7 @@ ca_path: /somewhere/ca.pem
 client_key: /somewhere/key.pem
 client_cert: /somewhere/cert.pem
 
+---
 # Example using constructed features to create groups
 plugin: community.docker.docker_containers
 docker_host: tcp://my-docker-host:2375
@@ -143,6 +148,7 @@ keyed_groups:
   - prefix: os
     key: docker_platform
 
+---
 # Example using SSH connection with an explicit fallback for when port 22 has not been
 # exported: use container name as ansible_ssh_host and 22 as ansible_ssh_port
 plugin: community.docker.docker_containers
@@ -151,6 +157,7 @@ compose:
   ansible_ssh_host: ansible_ssh_host | default(docker_name[1:], true)
   ansible_ssh_port: ansible_ssh_port | default(22, true)
 
+---
 # Only consider containers which have a label 'foo', or whose name starts with 'a'
 plugin: community.docker.docker_containers
 filters:
diff --git a/plugins/inventory/docker_machine.py b/plugins/inventory/docker_machine.py
index 6c0a8429..2415d96c 100644
--- a/plugins/inventory/docker_machine.py
+++ b/plugins/inventory/docker_machine.py
@@ -61,9 +61,11 @@ options:
 """
 
 EXAMPLES = '''
+---
 # Minimal example
 plugin: community.docker.docker_machine
 
+---
 # Example using constructed features to create a group per Docker Machine driver
 # (https://docs.docker.com/machine/drivers/), for example:
 #   $ docker-machine create --driver digitalocean ... mymachine
@@ -76,18 +78,23 @@ plugin: community.docker.docker_machine
 #       ]
 #     ...
 #   }
+plugin: community.docker.docker_machine
 strict: false
 keyed_groups:
   - separator: ''
     key: docker_machine_node_attributes.DriverName
 
+---
 # Example grouping hosts by Digital Machine tag
+plugin: community.docker.docker_machine
 strict: false
 keyed_groups:
   - prefix: tag
     key: 'dm_tags'
 
+---
 # Example using compose to override the default SSH behaviour of asking the user to accept the remote host key
+plugin: community.docker.docker_machine
 compose:
   ansible_ssh_common_args: '"-o StrictHostKeyChecking=accept-new"'
 '''
diff --git a/plugins/inventory/docker_swarm.py b/plugins/inventory/docker_swarm.py
index a26b8df8..6f223e07 100644
--- a/plugins/inventory/docker_swarm.py
+++ b/plugins/inventory/docker_swarm.py
@@ -107,19 +107,23 @@ options:
 """
 
 EXAMPLES = '''
+---
 # Minimal example using local docker
 plugin: community.docker.docker_swarm
 docker_host: unix:///var/run/docker.sock
 
+---
 # Minimal example using remote docker
 plugin: community.docker.docker_swarm
 docker_host: tcp://my-docker-host:2375
 
+---
 # Example using remote docker with unverified TLS
 plugin: community.docker.docker_swarm
 docker_host: tcp://my-docker-host:2376
 tls: true
 
+---
 # Example using remote docker with verified TLS and client certificate verification
 plugin: community.docker.docker_swarm
 docker_host: tcp://my-docker-host:2376
@@ -128,6 +132,7 @@ ca_path: /somewhere/ca.pem
 client_key: /somewhere/key.pem
 client_cert: /somewhere/cert.pem
 
+---
 # Example using constructed features to create groups and set ansible_host
 plugin: community.docker.docker_swarm
 docker_host: tcp://my-docker-host:2375
diff --git a/tests/sanity/ignore-2.15.txt b/tests/sanity/ignore-2.15.txt
index f717d24a..14ec3dfd 100644
--- a/tests/sanity/ignore-2.15.txt
+++ b/tests/sanity/ignore-2.15.txt
@@ -1,3 +1,6 @@
 .azure-pipelines/scripts/publish-codecov.py replace-urlopen
+plugins/inventory/docker_containers.py yamllint:unparsable-with-libyaml
+plugins/inventory/docker_machine.py yamllint:unparsable-with-libyaml
+plugins/inventory/docker_swarm.py yamllint:unparsable-with-libyaml
 plugins/modules/docker_container_copy_into.py validate-modules:undocumented-parameter # _max_file_size_for_diff is used by the action plugin
 plugins/modules/docker_image_build.py validate-modules:invalid-documentation
diff --git a/tests/sanity/ignore-2.16.txt b/tests/sanity/ignore-2.16.txt
index b60ad344..82720e59 100644
--- a/tests/sanity/ignore-2.16.txt
+++ b/tests/sanity/ignore-2.16.txt
@@ -1,2 +1,5 @@
+plugins/inventory/docker_containers.py yamllint:unparsable-with-libyaml
+plugins/inventory/docker_machine.py yamllint:unparsable-with-libyaml
+plugins/inventory/docker_swarm.py yamllint:unparsable-with-libyaml
 plugins/modules/docker_container_copy_into.py validate-modules:undocumented-parameter # _max_file_size_for_diff is used by the action plugin
 plugins/modules/docker_image_build.py validate-modules:invalid-documentation