Merge pull request #9294 from westurner/dockerio_docs_wip

dockerio module: docs syntax and formatting

salt/states/dockerio.py

@@ -4,14 +4,23 @@
 Manage Docker containers
 ========================
 
-A Docker is a light-weight, portable, self-sufficient container.
+`Docker <https://en.wikipedia.org/wiki/Docker_(software)>`_
+is a lightweight, portable, self-sufficient software container
+based on `Linux Containers (LXC)
+<https://en.wikipedia.org/wiki/Linux_Containers>`_,
+`cgroups <https://en.wikipedia.org/wiki/Cgroups>`_, and the
+`Linux Kernel <https://en.wikipedia.org/wiki/Linux_kernel>`_.
+
+.. warning::
+
+    This state module is beta. The API is subject to change. No promise
+    as to performance or functionality is yet present.
 
 .. note::
 
-    This state module is beta; the API is subject to change and no promise
-    as to performance or functionality is yet present
-    This module requires a docker-py that support `version 1.6 of docker
-    remote API.
+    This state module requires a
+    `docker-py <https://github.com/dotcloud/docker-py>`_
+    which supports `Docker Remote API version 1.6
     <https://docs.docker.io/en/latest/api/docker_remote_api_v1.6/>`_.
 
 Available Functions
@@ -71,9 +80,9 @@
                - unless: grep -q something /var/log/foo
                - docker_unless: grep -q done /install_log
 
-Note:
-The docker Modules can't be called docker as
-it would conflict with the underlying binding modules: docker-py
+.. note:: The docker modules are named `dockerio` because
+   the name 'docker' would conflict with the underlying docker-py library.
+
 '''
 
 # Import python libs
@@ -96,14 +105,14 @@
 
 def __virtual__():
     '''
-    Only load if docker libs available
+    Only load if the docker libs are available (`import docker`).
     '''
     if HAS_DOCKER:
         return __virtualname__
     return False
 
 
-INVALID_RESPONSE = 'We did not get any expectable answer from docker'
+INVALID_RESPONSE = 'We did not get an acceptable answer from docker'
 VALID_RESPONSE = ''
 NOTSET = object()
 CONTAINER_GRAIN_ID = 'docker.containers.{id}.id'
@@ -204,15 +213,20 @@ def mod_watch(name, sfun=None, *args, **kw):
 
 def pulled(name, force=False, *args, **kwargs):
     '''
-    Pull an image from a docker registry
+    Pull an image from a docker registry. (`docker pull`)
 
-    Remember to look on the execution module to see how to ident yourself with
-    a registry
+    .. note:: The image must already be loaded in docker; see the
+       documentation for `docker login`, `docker pull`, `docker push`,
+       and `docker.import_image <https://github.com/dotcloud/docker-py#api>`_
+       (`docker import
+       <http://docs.docker.io/en/latest/commandline/cli/#import>`_).
 
     name
         Tag of the image
+
     force
-        pull even if the image is already pulled
+        Pull even if the image is already pulled
+
     '''
     ins = __salt('docker.inspect_image')
     iinfos = ins(name)
@@ -235,16 +249,15 @@ def built(name,
           timeout=None,
           *args, **kwargs):
     '''
-    Build a docker image from a dockerfile or an URL
-
-    You can either:
-        - give the url/branch/docker_dir
-        - give a path on the file system
+    Build a docker image from a path or URL to a dockerfile. (`docker build`)
 
     name
         Tag of the image
+
     path
-        URL or path in the filesystem to the dockerfile
+        URL (e.g. `url/branch/docker_dir/dockerfile`)
+        or filesystem path to the dockerfile
+
     '''
     ins = __salt('docker.inspect_image')
     iinfos = ins(name)
@@ -283,14 +296,20 @@ def installed(name,
               privileged=False,
               *args, **kwargs):
     '''
-    Build a new container from an image
+    Ensure that a container with the given name exists;
+    if not, build a new container from the specified image.
+    (`docker run`)
 
     name
-        name of the container
+        Name for the container
+
     image
-        the image from which to build this container
+        Image from which to build this container
+
     path
         Path in the filesystem to the dockerfile
+        XXX: TODO: does this support a URL?
+
     environment
         Environment variables for the container, either
             - a mapping of key, values
@@ -302,15 +321,26 @@ def installed(name,
     volumes
         List of volumes
 
-    For other parameters, please look at the module
-    documentation
+    For other parameters, see the `docker-py documentation
+    <https://github.com/dotcloud/docker-py#api>`_ for
+    `docker.create_container`
+    and the `docker CLI documentation
+    <http://docs.docker.io/en/latest/commandline/cli/#run>`_ for the
+    `docker run` command.
+
+    XXX TODO: It would be helpful to list the supported kwargs here.
 
     You can create it either by specifying :
 
         - an image
         - an absolute path on the filesystem
 
-    This mean that you need one of those two parameters:
+    This mean that you need one of those two parameters.
+
+    XXX TODO: Image appears to be a required parameter.
+
+    .. note:: This command does not verify that the named container
+       is running the specified image.
 
 
     '''
@@ -382,14 +412,15 @@ def installed(name,
 
 def absent(name):
     '''
-    Container should be absent or
-    will be killed, destroyed, and eventually we will remove the grain matching
-
-    You can match by either a container's name or id
+    Ensure that the container is absent; if not, it will
+    will be killed and destroyed. (`docker inspect`)
 
     name:
         Either the container name or id
 
+    .. note:: eventually the grain matching will be removed
+       XXX TODO: is this removed?
+
     '''
     ins_container = __salt__['docker.inspect_container']
     cinfos = ins_container(name)
@@ -417,12 +448,11 @@ def absent(name):
 
 def present(name):
     '''
-    Container should be present or this state will fail
-
-    You can match by either a state id or a container id
+    If a container with the given name is not present, this state will fail.
+    (`docker inspect`)
 
     name:
-        Either the state_id or container id
+        Either a `state_id` or container id
 
     '''
     ins_container = __salt('docker.inspect_container')
@@ -450,7 +480,7 @@ def run(name,
     You can match by either name or hostname
 
     name
-        command to run in the docker
+        command to run in the container
 
     cid
         Container id
@@ -462,16 +492,16 @@ def run(name,