Document attributes (#497)

* Add 'docker' action group attribute.

* Compatibility with older ansible-core releases.

* Fix typo.

* Docment standard attributes.

* Improve docs.

* Add shortcuts for common combinations.

plugins/connection/docker.py

@@ -11,19 +11,19 @@ from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
 DOCUMENTATION = '''
-    author:
-        - Lorin Hochestein (!UNKNOWN)
-        - Leendert Brouwer (!UNKNOWN)
-    name: docker
-    short_description: Run tasks in docker containers
-    description:
-        - 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.
-    options:
-      remote_addr:
+author:
+    - Lorin Hochestein (!UNKNOWN)
+    - Leendert Brouwer (!UNKNOWN)
+name: docker
+short_description: Run tasks in docker containers
+description:
+    - 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.
+options:
+    remote_addr:
         description:
             - The name of the container you want to access.
         default: inventory_hostname
@@ -31,7 +31,7 @@ DOCUMENTATION = '''
             - name: inventory_hostname
             - name: ansible_host
             - name: ansible_docker_host
-      remote_user:
+    remote_user:
         description:
             - The user to execute as inside the container.
             - If Docker is too old to allow this (< 1.7), the one set by Docker itself will be used.
@@ -47,7 +47,7 @@ DOCUMENTATION = '''
             - name: user
         keyword:
             - name: remote_user
-      docker_extra_args:
+    docker_extra_args:
         description:
             - Extra arguments to pass to the docker command line.
         default: ''
@@ -56,7 +56,7 @@ DOCUMENTATION = '''
         ini:
             - section: docker_connection
               key: extra_cli_args
-      container_timeout:
+    container_timeout:
         default: 10
         description:
             - Controls how long we can wait to access reading output from the container once execution started.

plugins/connection/docker_api.py

@@ -17,6 +17,9 @@ description:
       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.
+extends_documentation_fragment:
+    - community.docker.docker.api_documentation
+    - community.docker.docker.var_names
 options:
     remote_user:
         type: str
@@ -63,10 +66,6 @@ options:
         cli:
             - name: timeout
         type: integer
-
-extends_documentation_fragment:
-    - community.docker.docker.api_documentation
-    - community.docker.docker.var_names
 '''
 
 import io

plugins/connection/nsenter.py

@@ -9,38 +9,38 @@ from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
 DOCUMENTATION = '''
-    name: nsenter
-    short_description: execute on host running controller container
-    version_added: 1.9.0
-    description:
-        - This connection plugin allows Ansible, running in a privileged container, to execute tasks on the container
-          host instead of in the container itself.
-        - This is useful for running Ansible in a pull model, while still keeping the Ansible control node
-          containerized.
-        - It relies on having privileged access to run C(nsenter) in the host's PID namespace, allowing it to enter the
-          namespaces of the provided PID (default PID 1, or init/systemd).
-    author: Jeff Goldschrafe (@jgoldschrafe)
-    options:
-        nsenter_pid:
-            description:
-                - PID to attach with using nsenter.
-                - The default should be fine unless you are attaching as a non-root user.
-            type: int
-            default: 1
-            vars:
-                - name: ansible_nsenter_pid
-            env:
-                - name: ANSIBLE_NSENTER_PID
-            ini:
-                - section: nsenter_connection
-                  key: nsenter_pid
-    notes:
-        - The remote user is ignored; this plugin always runs as root.
-        - >-
-            This plugin requires the Ansible controller container to be launched in the following way:
-            (1) The container image contains the C(nsenter) program;
-            (2) The container is launched in privileged mode;
-            (3) The container is launched in the host's PID namespace (C(--pid host)).
+name: nsenter
+short_description: execute on host running controller container
+version_added: 1.9.0
+description:
+    - This connection plugin allows Ansible, running in a privileged container, to execute tasks on the container
+      host instead of in the container itself.
+    - This is useful for running Ansible in a pull model, while still keeping the Ansible control node
+      containerized.
+    - It relies on having privileged access to run C(nsenter) in the host's PID namespace, allowing it to enter the
+      namespaces of the provided PID (default PID 1, or init/systemd).
+author: Jeff Goldschrafe (@jgoldschrafe)
+options:
+    nsenter_pid:
+        description:
+            - PID to attach with using nsenter.
+            - The default should be fine unless you are attaching as a non-root user.
+        type: int
+        default: 1
+        vars:
+            - name: ansible_nsenter_pid
+        env:
+            - name: ANSIBLE_NSENTER_PID
+        ini:
+            - section: nsenter_connection
+              key: nsenter_pid
+notes:
+    - The remote user is ignored; this plugin always runs as root.
+    - >-
+        This plugin requires the Ansible controller container to be launched in the following way:
+        (1) The container image contains the C(nsenter) program;
+        (2) The container is launched in privileged mode;
+        (3) The container is launched in the host's PID namespace (C(--pid host)).
 '''
 
 import os