Docker: mention Docker SDK for Python instead of docker/docker-py (#53917)

* Mention Docker SDK for Python instead of docker-py / docker.

* Docs fixes.

* Add myself as docker_container author.

* Use array syntax for running command.

* Break long lines.

* Avoid failure when docker_version is None.

* Improve docker-py vs. docker note in requirements.

* Canonicalize Docker SDK for Python upgrade instructions.

* Split long line.

* Make it clearer which hostnames are meant.

lib/ansible/plugins/doc_fragments/docker.py

@@ -29,7 +29,7 @@ options:
     api_version:
         description:
             - The version of the Docker API running on the Docker Host.
-            - Defaults to the latest version of the API supported by docker-py.
+            - Defaults to the latest version of the API supported by Docker SDK for Python and the docker daemon.
             - If the value is not specified in the task, the value of environment variable C(DOCKER_API_VERSION) will be
               used instead. If the environment variable is not set, the default value will be used.
         type: str
@@ -103,13 +103,13 @@ notes:
     and use C($DOCKER_CONFIG/config.json) otherwise.
 '''
 
-    # Additional, more specific stuff for minimal docker-py version < 2.0
+    # Additional, more specific stuff for minimal Docker SDK for Python version < 2.0
 
     DOCKER_PY_1_DOCUMENTATION = r'''
 options: {}
 requirements:
-  - "Please note that the L(docker-py,https://pypi.org/project/docker-py/) Python
-     module has been superseded by L(docker,https://pypi.org/project/docker/)
+  - "Docker SDK for Python: Please note that the L(docker-py,https://pypi.org/project/docker-py/)
+     Python module has been superseded by L(docker,https://pypi.org/project/docker/)
      (see L(here,https://github.com/docker/docker-py/issues/1310) for details).
      For Python 2.6, C(docker-py) must be used. Otherwise, it is recommended to
      install the C(docker) Python module. Note that both modules should I(not)
@@ -118,15 +118,15 @@ requirements:
      reinstall of it is required."
 '''
 
-    # Additional, more specific stuff for minimal docker-py version >= 2.0.
-    # Note that docker-py >= 2.0 requires Python 2.7 or newer.
+    # Additional, more specific stuff for minimal Docker SDK for Python version >= 2.0.
+    # Note that Docker SDK for Python >= 2.0 requires Python 2.7 or newer.
 
     DOCKER_PY_2_DOCUMENTATION = r'''
 options: {}
 requirements:
   - "Python >= 2.7"
-  - "Please note that the L(docker-py,https://pypi.org/project/docker-py/) Python
-     module has been superseded by L(docker,https://pypi.org/project/docker/)
+  - "Docker SDK for Python: Please note that the L(docker-py,https://pypi.org/project/docker-py/)
+     Python module has been superseded by L(docker,https://pypi.org/project/docker/)
      (see L(here,https://github.com/docker/docker-py/issues/1310) for details).
      This module does I(not) work with docker-py."
 '''

lib/ansible/plugins/inventory/docker_swarm.py

@@ -16,7 +16,7 @@ DOCUMENTATION = '''
     short_description: Ansible dynamic inventory plugin for Docker swarm nodes.
     requirements:
         - python >= 2.7
-        - Docker SDK for Python > 1.10.0
+        - L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 1.10.0
     extends_documentation_fragment:
         - constructed
     description:
@@ -24,7 +24,7 @@ DOCUMENTATION = '''
         - Uses a YAML configuration file docker_swarm.[yml|yaml].
     options:
         plugin:
-            description: The name of this plugin, it should always be set to 'docker_swarm' for this plugin to recognize it as it's own.
+            description: The name of this plugin, it should always be set to C(docker_swarm) for this plugin to recognize it as it's own.
             type: str
             required: true
             choices: docker_swarm
@@ -56,7 +56,7 @@ DOCUMENTATION = '''
             description: Path to the client's TLS certificate file.
             type: path
         tls_hostname:
-            description: When verifying the authenticity of the Docker Host server, provide the expected name of the server.
+            description: When verifying the authenticity of the Docker host server, provide the expected name of the server.
             type: str
         ssl_version:
             description: Provide a valid SSL version number. Default value determined by ssl.py module.