Use semantic markup

docs/docsite/config.yml

@@ -0,0 +1,15 @@
+---
+# 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
+
+# The following `.. envvar::` directives are defined in the extra docsite docs:
+envvar_directives:
+  - DOCKER_HOST
+  - DOCKER_API_VERSION
+  - DOCKER_TIMEOUT
+  - DOCKER_CERT_PATH
+  - DOCKER_SSL_VERSION
+  - DOCKER_TLS
+  - DOCKER_TLS_HOSTNAME
+  - DOCKER_TLS_VERIFY

docs/docsite/rst/scenario_guide.rst

@@ -86,27 +86,38 @@ You can also control how the plugins and modules connect to the Docker API by se
 
 For plugins, they have to be set for the environment Ansible itself runs in. For modules, they have to be set for the environment the modules are executed in. For modules running on remote machines, the environment variables have to be set on that machine for the user used to execute the modules with.
 
-    DOCKER_HOST
-        The URL or Unix socket path used to connect to the Docker API.
+.. envvar:: DOCKER_HOST
 
-    DOCKER_API_VERSION
-        The version of the Docker API running on the Docker Host. Defaults to the latest version of the API supported
-        by Docker SDK for Python.
+    The URL or Unix socket path used to connect to the Docker API.
 
-    DOCKER_TIMEOUT
-        The maximum amount of time in seconds to wait on a response from the API.
+.. envvar:: DOCKER_API_VERSION
 
-    DOCKER_CERT_PATH
-        Path to the directory containing the client certificate, client key and CA certificate.
+    The version of the Docker API running on the Docker Host. Defaults to the latest version of the API supported
+    by Docker SDK for Python.
 
-    DOCKER_SSL_VERSION
-        Provide a valid SSL version number.
+.. envvar:: DOCKER_TIMEOUT
 
-    DOCKER_TLS
-        Secure the connection to the API by using TLS without verifying the authenticity of the Docker Host.
+    The maximum amount of time in seconds to wait on a response from the API.
 
-    DOCKER_TLS_VERIFY
-        Secure the connection to the API by using TLS and verify the authenticity of the Docker Host.
+.. envvar:: DOCKER_CERT_PATH
+
+    Path to the directory containing the client certificate, client key and CA certificate.
+
+.. envvar:: DOCKER_SSL_VERSION
+
+    Provide a valid SSL version number.
+
+.. envvar:: DOCKER_TLS
+
+    Secure the connection to the API by using TLS without verifying the authenticity of the Docker Host.
+
+.. envvar:: DOCKER_TLS_HOSTNAME
+
+    When verifying the authenticity of the Docker Host, uses this hostname to compare to the host's certificate.
+
+.. envvar:: DOCKER_TLS_VERIFY
+
+    Secure the connection to the API by using TLS and verify the authenticity of the Docker Host.
 
 
 Plain Docker daemon: images, networks, volumes, and containers

plugins/connection/docker.py

@@ -20,8 +20,7 @@
     - Run commands or put/fetch files to an existing docker container.
     - Uses the Docker CLI to execute commands in the container. If you prefer
       to directly connect to the Docker daemon, use the
-      R(community.docker.docker_api,ansible_collections.community.docker.docker_api_connection)
-      connection plugin.
+      P(community.docker.docker_api#connection) connection plugin.
 options:
     remote_addr:
         description:

plugins/connection/docker_api.py

@@ -15,8 +15,7 @@
     - Run commands or put/fetch files to an existing docker container.
     - Uses the L(requests library,https://pypi.org/project/requests/) to interact
       directly with the Docker daemon instead of using the Docker CLI. Use the
-      R(community.docker.docker,ansible_collections.community.docker.docker_connection)
-      connection plugin if you want to use the Docker CLI.
+      P(community.docker.docker#connection) connection plugin if you want to use the Docker CLI.
 notes:
     - Does B(not work with TCP TLS sockets)! This is caused by the inability to send C(close_notify) without closing the connection
       with Python's C(SSLSocket)s. See U(https://github.com/ansible-collections/community.docker/issues/605) for more information.

plugins/inventory/docker_containers.py

@@ -27,7 +27,7 @@
 options:
     plugin:
         description:
-            - The name of this plugin, it should always be set to C(community.docker.docker_containers)
+            - The name of this plugin, it should always be set to V(community.docker.docker_containers)
               for this plugin to recognize it as it's own.
         type: str
         required: true
@@ -36,17 +36,14 @@
     connection_type:
         description:
             - Which connection type to use the containers.
-            - One way to connect to containers is to use SSH (C(ssh)). For this, the options I(default_ip) and
-              I(private_ssh_port) are used. This requires that a SSH daemon is running inside the containers.
-            - Alternatively, C(docker-cli) selects the
-              R(docker connection plugin,ansible_collections.community.docker.docker_connection),
-              and C(docker-api) (default) selects the
-              R(docker_api connection plugin,ansible_collections.community.docker.docker_api_connection).
-            - When C(docker-api) is used, all Docker daemon configuration values are passed from the inventory plugin
-              to the connection plugin. This can be controlled with I(configure_docker_daemon).
-            - Note that the R(docker_api connection plugin,ansible_collections.community.docker.docker_api_connection)
-              does B(not work with TCP TLS sockets)! See U(https://github.com/ansible-collections/community.docker/issues/605)
-              for more information.
+            - One way to connect to containers is to use SSH (V(ssh)). For this, the options O(default_ip) and
+              O(private_ssh_port) are used. This requires that a SSH daemon is running inside the containers.
+            - Alternatively, V(docker-cli) selects the P(community.docker.docker#connection) connection plugin,
+              and V(docker-api) (default) selects the P(community.docker.docker_api#connection) connection plugin.
+            - When V(docker-api) is used, all Docker daemon configuration values are passed from the inventory plugin
+              to the connection plugin. This can be controlled with O(configure_docker_daemon).
+            - Note that the P(community.docker.docker_api#connection) does B(not work with TCP TLS sockets)!
+              See U(https://github.com/ansible-collections/community.docker/issues/605) for more information.
         type: str
         default: docker-api
         choices:
@@ -57,7 +54,7 @@
     configure_docker_daemon:
         description:
             - Whether to pass all Docker daemon configuration from the inventory plugin to the connection plugin.
-            - Only used when I(connection_type=docker-api).
+            - Only used when O(connection_type=docker-api).
         type: bool
         default: true
         version_added: 1.8.0
@@ -67,23 +64,23 @@
             - Toggle to (not) include all available inspection metadata.
             - Note that all top-level keys will be transformed to the format C(docker_xxx).
               For example, C(HostConfig) is converted to C(docker_hostconfig).
-            - If this is C(false), these values can only be used during I(constructed), I(groups), and I(keyed_groups).
-            - The C(docker) inventory script always added these variables, so for compatibility set this to C(true).
+            - If this is V(false), these values can only be used during O(compose), O(groups), and O(keyed_groups).
+            - The C(docker) inventory script always added these variables, so for compatibility set this to V(true).
         type: bool
         default: false
 
     default_ip:
         description:
             - The IP address to assign to ansible_host when the container's SSH port is mapped to interface
               '0.0.0.0'.
-            - Only used if I(connection_type) is C(ssh).
+            - Only used if O(connection_type) is V(ssh).
         type: str
         default: 127.0.0.1
 
     private_ssh_port:
         description:
             - The port containers use for SSH.
-            - Only used if I(connection_type) is C(ssh).
+            - Only used if O(connection_type) is V(ssh).
         type: int
         default: 22
 
@@ -96,11 +93,11 @@
             - "C(image_<image name>): contains the containers that have the image C(<image name>)."
             - "C(stack_<stack name>): contains the containers that belong to the stack C(<stack name>)."
             - "C(service_<service name>): contains the containers that belong to the service C(<service name>)"
-            - "C(<docker_host>): contains the containers which belong to the Docker daemon I(docker_host).
+            - "C(<docker_host>): contains the containers which belong to the Docker daemon O(docker_host).
               Useful if you run this plugin against multiple Docker daemons."
             - "C(running): contains all containers that are running."
             - "C(stopped): contains all containers that are not running."
-            - If this is not set to C(true), you should use keyed groups to add the containers to groups.
+            - If this is not set to V(true), you should use keyed groups to add the containers to groups.
               See the examples for how to do that.
         type: bool
         default: false

plugins/inventory/docker_machine.py

@@ -18,7 +18,7 @@
         - Get inventory hosts from Docker Machine.
         - Uses a YAML configuration file that ends with docker_machine.(yml|yaml).
         - The plugin sets standard host variables C(ansible_host), C(ansible_port), C(ansible_user) and C(ansible_ssh_private_key).
-        - The plugin stores the Docker Machine 'env' output variables in I(dm_) prefixed host variables.
+        - The plugin stores the Docker Machine 'env' output variables in C(dm_) prefixed host variables.
 
     options:
         plugin:
@@ -28,12 +28,12 @@
         daemon_env:
             description:
                 - Whether docker daemon connection environment variables should be fetched, and how to behave if they cannot be fetched.
-                - With C(require) and C(require-silently), fetch them and skip any host for which they cannot be fetched.
-                  A warning will be issued for any skipped host if the choice is C(require).
-                - With C(optional) and C(optional-silently), fetch them and not skip hosts for which they cannot be fetched.
-                  A warning will be issued for hosts where they cannot be fetched if the choice is C(optional).
-                - With C(skip), do not attempt to fetch the docker daemon connection environment variables.
-                - If fetched successfully, the variables will be prefixed with I(dm_) and stored as host variables.
+                - With V(require) and V(require-silently), fetch them and skip any host for which they cannot be fetched.
+                  A warning will be issued for any skipped host if the choice is V(require).
+                - With V(optional) and V(optional-silently), fetch them and not skip hosts for which they cannot be fetched.
+                  A warning will be issued for hosts where they cannot be fetched if the choice is V(optional).
+                - With V(skip), do not attempt to fetch the docker daemon connection environment variables.
+                - If fetched successfully, the variables will be prefixed with C(dm_) and stored as host variables.
             type: str
             choices:
                 - require
@@ -44,12 +44,12 @@
             default: require
         running_required:
             description:
-                - When C(true), hosts which Docker Machine indicates are in a state other than C(running) will be skipped.
+                - When V(true), hosts which Docker Machine indicates are in a state other than C(running) will be skipped.
             type: bool
             default: true
         verbose_output:
             description:
-                - When C(true), include all available nodes metadata (for exmaple C(Image), C(Region), C(Size)) as a JSON object
+                - When V(true), include all available nodes metadata (for exmaple C(Image), C(Region), C(Size)) as a JSON object
                   named C(docker_machine_node_attributes).
             type: bool
             default: true

plugins/inventory/docker_swarm.py

@@ -21,26 +21,26 @@
     description:
         - Reads inventories from the Docker swarm API.
         - Uses a YAML configuration file docker_swarm.[yml|yaml].
-        - "The plugin returns following groups of swarm nodes:  I(all) - all hosts; I(workers) - all worker nodes;
-          I(managers) - all manager nodes; I(leader) - the swarm leader node;
-          I(nonleaders) - all nodes except the swarm leader."
+        - "The plugin returns following groups of swarm nodes:  C(all) - all hosts; C(workers) - all worker nodes;
+          C(managers) - all manager nodes; C(leader) - the swarm leader node;
+          C(nonleaders) - all nodes except the swarm leader."
     options:
         plugin:
-            description: The name of this plugin, it should always be set to C(community.docker.docker_swarm)
+            description: The name of this plugin, it should always be set to V(community.docker.docker_swarm)
                          for this plugin to recognize it as it's own.
             type: str
             required: true
             choices: [ docker_swarm, community.docker.docker_swarm ]
         docker_host:
             description:
                 - Socket of a Docker swarm manager node (C(tcp), C(unix)).
-                - "Use C(unix://var/run/docker.sock) to connect via local socket."
+                - "Use V(unix://var/run/docker.sock) to connect via local socket."
             type: str
             required: true
             aliases: [ docker_url ]
         verbose_output:
             description: Toggle to (not) include all available nodes metadata (for example C(Platform), C(Architecture), C(OS),
-                         C(EngineVersion))
+                         C(EngineVersion)).
             type: bool
             default: true
         tls:
@@ -71,7 +71,9 @@
                          the server.
             type: str
         ssl_version:
-            description: Provide a valid SSL version number. Default value determined by ssl.py module.
+            description:
+                - Provide a valid SSL version number. Default value determined
+                  by L(SSL Python module, https://docs.python.org/3/library/ssl.html).
             type: str
         api_version:
             description:
@@ -82,7 +84,7 @@
         timeout:
             description:
                 - The maximum amount of time in seconds to wait on a response from the API.
-                - If the value is not specified in the task, the value of environment variable C(DOCKER_TIMEOUT)
+                - If the value is not specified in the task, the value of environment variable E(DOCKER_TIMEOUT).
                   will be used instead. If the environment variable is not set, the default value will be used.
             type: int
             default: 60
@@ -96,13 +98,13 @@
             version_added: 1.5.0
         include_host_uri:
             description: Toggle to return the additional attribute C(ansible_host_uri) which contains the URI of the
-                         swarm leader in format of C(tcp://172.16.0.1:2376). This value may be used without additional
-                         modification as value of option I(docker_host) in Docker Swarm modules when connecting via API.
-                         The port always defaults to C(2376).
+                         swarm leader in format of V(tcp://172.16.0.1:2376). This value may be used without additional
+                         modification as value of option O(docker_host) in Docker Swarm modules when connecting via API.
+                         The port always defaults to V(2376).
             type: bool
             default: false
         include_host_uri_port:
-            description: Override the detected port number included in I(ansible_host_uri)
+            description: Override the detected port number included in C(ansible_host_uri).
             type: int
 '''
 

plugins/modules/current_container_facts.py

@@ -58,10 +58,10 @@
             description:
               - The detected container environment.
               - Contains an empty string if no container was detected, or a non-empty string identifying the container environment.
-              - C(docker) indicates that the module ran inside a regular Docker container.
-              - C(azure_pipelines) indicates that the module ran on Azure Pipelines. This seems to no longer be reported.
-              - C(github_actions) indicates that the module ran inside a Docker container on GitHub Actions. It is supported since community.docker 2.4.0.
-              - C(podman) indicates that the module ran inside a regular Podman container. It is supported since community.docker 3.3.0.
+              - V(docker) indicates that the module ran inside a regular Docker container.
+              - V(azure_pipelines) indicates that the module ran on Azure Pipelines. This seems to no longer be reported.
+              - V(github_actions) indicates that the module ran inside a Docker container on GitHub Actions. It is supported since community.docker 2.4.0.
+              - V(podman) indicates that the module ran inside a regular Podman container. It is supported since community.docker 3.3.0.
             returned: always
             type: str
             choices: