Fix documentation fragments for docker (#38378)

lib/ansible/module_utils/docker_common.py

@@ -37,7 +37,7 @@ try:
     from docker import __version__ as docker_version
     from docker.errors import APIError, TLSParameterError, NotFound
     from docker.tls import TLSConfig
-    from docker.constants import DEFAULT_TIMEOUT_SECONDS, DEFAULT_DOCKER_API_VERSION
+    from docker.constants import DEFAULT_DOCKER_API_VERSION
     from docker import auth
 
     if LooseVersion(docker_version) >= LooseVersion('3.0.0'):
@@ -78,21 +78,23 @@ except ImportError:
 DEFAULT_DOCKER_HOST = 'unix://var/run/docker.sock'
 DEFAULT_TLS = False
 DEFAULT_TLS_VERIFY = False
+DEFAULT_TLS_HOSTNAME = 'localhost'
 MIN_DOCKER_VERSION = "1.7.0"
+DEFAULT_SSL_VERSION = "1.0"
+DEFAULT_TIMEOUT_SECONDS = 60
 
 DOCKER_COMMON_ARGS = dict(
-    docker_host=dict(type='str', aliases=['docker_url']),
-    tls_hostname=dict(type='str'),
-    api_version=dict(type='str', aliases=['docker_api_version']),
-    timeout=dict(type='int'),
+    docker_host=dict(type='str', aliases=['docker_url'], default=DEFAULT_DOCKER_HOST),
+    tls_hostname=dict(type='str', default=DEFAULT_TLS_HOSTNAME),
+    api_version=dict(type='str', aliases=['docker_api_version'], default='auto'),
+    timeout=dict(type='int', default=DEFAULT_TIMEOUT_SECONDS),
     cacert_path=dict(type='str', aliases=['tls_ca_cert']),
     cert_path=dict(type='str', aliases=['tls_client_cert']),
     key_path=dict(type='str', aliases=['tls_client_key']),
-    ssl_version=dict(type='str'),
-    tls=dict(type='bool'),
-    tls_verify=dict(type='bool'),
-    debug=dict(type='bool', default=False),
-    filter_logger=dict(type='bool', default=False),
+    ssl_version=dict(type='str', default=DEFAULT_SSL_VERSION),
+    tls=dict(type='bool', default=DEFAULT_TLS),
+    tls_verify=dict(type='bool', default=DEFAULT_TLS_VERIFY),
+    debug=dict(type='bool', default=False)
 )
 
 DOCKER_MUTUALLY_EXCLUSIVE = [

lib/ansible/modules/cloud/docker/docker_container.py

@@ -69,10 +69,15 @@ options:
     description:
       - Enable detached mode to leave the container running in background.
         If disabled, the task will reflect the status of the container run (failed if the command failed).
+    type: bool
+    default: true
   devices:
     description:
       - "List of host device bindings to add to the container. Each binding is a mapping expressed
         in the format: <path_on_host>:<path_in_container>:<cgroup_permissions>"
+  dns_opts:
+    description:
+      - list of DNS options
   dns_servers:
     description:
       - List of custom DNS servers.
@@ -107,11 +112,14 @@ options:
         need to be exposed again.
     aliases:
       - exposed
+      - expose
   force_kill:
     description:
       - Use the kill command when stopping a running container.
     type: bool
     default: 'no'
+    aliases:
+      - forcekill
   groups:
     description:
       - List of additional group names and/or IDs that the container process will run as.
@@ -175,6 +183,8 @@ options:
     description:
       - Dictionary of options specific to the chosen log_driver. See https://docs.docker.com/engine/admin/logging/overview/
         for details.
+    aliases:
+      - log_opt
   mac_address:
     description:
       - Container MAC address (e.g. 92:d0:c6:0a:29:33)
@@ -182,7 +192,7 @@ options:
     description:
       - "Memory limit (format: <number>[<unit>]). Number is a positive integer.
         Unit can be one of b, k, m, or g"
-    default: 0
+    default: '0'
   memory_reservation:
     description:
       - "Memory soft limit (format: <number>[<unit>]). Number is a positive integer.
@@ -204,12 +214,7 @@ options:
     required: true
   network_mode:
     description:
-      - Connect the container to a network.
-    choices:
-      - bridge
-      - container:<name|id>
-      - host
-      - none
+      - Connect the container to a network. Choices are "bridge", "host", "none" or "container:<name|id>"
   userns_mode:
      description:
        - User namespace to use
@@ -293,11 +298,10 @@ options:
     description:
       - Container restart policy. Place quotes around I(no) option.
     choices:
-      - always
-      - no
-      - on-failure
-      - unless-stopped
-    default: on-failure
+      - 'no'
+      - 'on-failure'
+      - 'always'
+      - 'unless-stopped'
   restart_retries:
     description:
        - Use with restart policy to control maximum number of restart attempts.

lib/ansible/modules/cloud/docker/docker_image.py

@@ -38,7 +38,6 @@ options:
   dockerfile:
     description:
       - Use with state C(present) to provide an alternate name for the Dockerfile to use when building an image.
-    default: Dockerfile
     required: false
     version_added: "2.0"
   force:
@@ -156,10 +155,10 @@ options:
         C(encrypt) to use TLS. And set to C(verify) to use TLS and verify that the server's certificate is valid for the
         server. NOTE: If you specify this option, it will set the value of the tls or tls_verify parameters."
     choices:
-      - no
-      - encrypt
-      - verify
-    default: no
+      - 'no'
+      - 'encrypt'
+      - 'verify'
+    default: 'no'
     required: false
     version_added: "2.0"
 

lib/ansible/modules/cloud/docker/docker_secret.py

@@ -38,9 +38,10 @@ options:
     required: false
   force:
     description:
-      - Boolean. Use with state C(present) to always remove and recreate an existing secret.
+      - Use with state C(present) to always remove and recreate an existing secret.
       - If I(true), an existing secret will be replaced, even if it has not changed.
     default: false
+    type: bool
   name:
     description:
       - The name of the secret.

lib/ansible/modules/cloud/docker/docker_service.py

@@ -110,6 +110,9 @@ options:
   remove_images:
       description:
         - Use with state I(absent) to remove the all images or only local images.
+      choices:
+          - 'all'
+          - 'local'
   remove_volumes:
       description:
         - Use with state I(absent) to remove data volumes.
@@ -125,11 +128,15 @@ options:
         - Use with state I(present) to restart all containers.
       type: bool
       default: 'no'
-  debug:
+  remove_orphans:
       description:
-        - Include I(actions) in the return values.
+        - Remove containers for services not defined in the compose file.
       type: bool
-      default: 'no'
+      default: false
+  timeout:
+    description:
+        - timeout in seconds for container shutdown when attached or when containers are already running.
+    default: 10
 
 extends_documentation_fragment:
     - docker

lib/ansible/utils/module_docs_fragments/docker.py

@@ -37,7 +37,7 @@ options:
         description:
             - The version of the Docker API running on the Docker Host. Defaults to the latest version of the API
               supported by docker-py.
-        default: default provided by docker-py
+        default: 'auto'
         aliases:
             - docker_api_version
     timeout:
@@ -67,9 +67,18 @@ options:
         description:
             -  Secure the connection to the API by using TLS without verifying the authenticity of the Docker host
                server.
+        default: false
+        type: bool
     tls_verify:
         description:
             - Secure the connection to the API by using TLS and verifying the authenticity of the Docker host server.
+        default: false
+        type: bool
+    debug:
+        description:
+            - Debug mode
+        default: false
+        type: bool
 
 notes:
     - Connect to the Docker daemon by providing parameters with each task or by defining environment variables.

test/sanity/validate-modules/ignore.txt

@@ -317,33 +317,6 @@ lib/ansible/modules/cloud/dimensiondata/dimensiondata_network.py E325
 lib/ansible/modules/cloud/dimensiondata/dimensiondata_network.py E326
 lib/ansible/modules/cloud/dimensiondata/dimensiondata_vlan.py E325
 lib/ansible/modules/cloud/dimensiondata/dimensiondata_vlan.py E326
-lib/ansible/modules/cloud/docker/docker_container.py E322
-lib/ansible/modules/cloud/docker/docker_container.py E324
-lib/ansible/modules/cloud/docker/docker_container.py E325
-lib/ansible/modules/cloud/docker/docker_container.py E326
-lib/ansible/modules/cloud/docker/docker_image.py E322
-lib/ansible/modules/cloud/docker/docker_image.py E324
-lib/ansible/modules/cloud/docker/docker_image.py E325
-lib/ansible/modules/cloud/docker/docker_image.py E326
-lib/ansible/modules/cloud/docker/docker_image_facts.py E322
-lib/ansible/modules/cloud/docker/docker_image_facts.py E324
-lib/ansible/modules/cloud/docker/docker_image_facts.py E325
-lib/ansible/modules/cloud/docker/docker_login.py E322
-lib/ansible/modules/cloud/docker/docker_login.py E324
-lib/ansible/modules/cloud/docker/docker_login.py E325
-lib/ansible/modules/cloud/docker/docker_network.py E322
-lib/ansible/modules/cloud/docker/docker_network.py E324
-lib/ansible/modules/cloud/docker/docker_network.py E325
-lib/ansible/modules/cloud/docker/docker_secret.py E322
-lib/ansible/modules/cloud/docker/docker_secret.py E324
-lib/ansible/modules/cloud/docker/docker_secret.py E325
-lib/ansible/modules/cloud/docker/docker_service.py E322
-lib/ansible/modules/cloud/docker/docker_service.py E324
-lib/ansible/modules/cloud/docker/docker_service.py E325
-lib/ansible/modules/cloud/docker/docker_service.py E326
-lib/ansible/modules/cloud/docker/docker_volume.py E322
-lib/ansible/modules/cloud/docker/docker_volume.py E324
-lib/ansible/modules/cloud/docker/docker_volume.py E325
 lib/ansible/modules/cloud/google/gc_storage.py E322
 lib/ansible/modules/cloud/google/gc_storage.py E324
 lib/ansible/modules/cloud/google/gc_storage.py E325