Merge pull request #1398 from docker/docs-fixes

Fix a number of docs formatting issues

11 files changed, 96 insertions, 101 deletions

diff --git a/docker/api/container.py b/docker/api/container.py
index afe696c..efcae9b 100644
--- a/docker/api/container.py
+++ b/docker/api/container.py
@@ -388,13 +388,13 @@ class ContainerApiMixin(object):
             environment (dict or list): A dictionary or a list of strings in
                 the following format ``["PASSWORD=xxx"]`` or
                 ``{"PASSWORD": "xxx"}``.
-            dns (list): DNS name servers. Deprecated since API version 1.10.
-                Use ``host_config`` instead.
-            dns_opt (list): Additional options to be added to the container's
-                ``resolv.conf`` file
+            dns (:py:class:`list`): DNS name servers. Deprecated since API
+                version 1.10. Use ``host_config`` instead.
+            dns_opt (:py:class:`list`): Additional options to be added to the
+                container's ``resolv.conf`` file
             volumes (str or list):
-            volumes_from (list): List of container names or Ids to get
-                volumes from.
+            volumes_from (:py:class:`list`): List of container names or Ids to
+                get volumes from.
             network_disabled (bool): Disable networking
             name (str): A name for the container
             entrypoint (str or list): An entrypoint
@@ -478,19 +478,19 @@ class ContainerApiMixin(object):
             device_write_bps: Limit write rate (bytes per second) from a
                 device.
             device_write_iops: Limit write rate (IO per second) from a device.
-            devices (list): Expose host devices to the container, as a list
-                of strings in the form
+            devices (:py:class:`list`): Expose host devices to the container,
+                as a list of strings in the form
                 ``<path_on_host>:<path_in_container>:<cgroup_permissions>``.
 
                 For example, ``/dev/sda:/dev/xvda:rwm`` allows the container
                 to have read-write access to the host's ``/dev/sda`` via a
                 node named ``/dev/xvda`` inside the container.
-            dns (list): Set custom DNS servers.
-            dns_search (list): DNS search domains.
+            dns (:py:class:`list`): Set custom DNS servers.
+            dns_search (:py:class:`list`): DNS search domains.
             extra_hosts (dict): Addtional hostnames to resolve inside the
                 container, as a mapping of hostname to IP address.
-            group_add (list): List of additional group names and/or IDs that
-                the container process will run as.
+            group_add (:py:class:`list`): List of additional group names and/or
+                IDs that the container process will run as.
             ipc_mode (str): Set the IPC mode for the container.
             isolation (str): Isolation technology to use. Default: `None`.
             links (dict or list of tuples): Either a dictionary mapping name
@@ -539,8 +539,8 @@ class ContainerApiMixin(object):
                 - ``Name`` One of ``on-failure``, or ``always``.
                 - ``MaximumRetryCount`` Number of times to restart the
                   container on failure.
-            security_opt (list): A list of string values to customize labels
-                for MLS systems, such as SELinux.
+            security_opt (:py:class:`list`): A list of string values to
+                customize labels for MLS systems, such as SELinux.
             shm_size (str or int): Size of /dev/shm (e.g. ``1G``).
             sysctls (dict): Kernel parameters to set in the container.
             tmpfs (dict): Temporary filesystems to mount, as a dictionary
@@ -555,13 +555,13 @@ class ContainerApiMixin(object):
                         '/mnt/vol1': 'size=3G,uid=1000'
                     }
 
-            ulimits (list): Ulimits to set inside the container, as a list of
-                dicts.
+            ulimits (:py:class:`list`): Ulimits to set inside the container,
+                as a list of dicts.
             userns_mode (str): Sets the user namespace mode for the container
                 when user namespace remapping option is enabled. Supported
                 values are: ``host``
-            volumes_from (list): List of container names or IDs to get
-                volumes from.
+            volumes_from (:py:class:`list`): List of container names or IDs to
+                get volumes from.
 
 
         Returns:
@@ -618,17 +618,17 @@ class ContainerApiMixin(object):
         :py:meth:`create_networking_config`.
 
         Args:
-            aliases (list): A list of aliases for this endpoint. Names in
-                that list can be used within the network to reach the
+            aliases (:py:class:`list`): A list of aliases for this endpoint.
+                Names in that list can be used within the network to reach the
+                container. Defaults to ``None``.
+            links (:py:class:`list`): A list of links for this endpoint.
+                Containers declared in this list will be linked to this
                 container. Defaults to ``None``.
-            links (list): A list of links for this endpoint. Containers
-                declared in this list will be linked to this container.
-                Defaults to ``None``.
             ipv4_address (str): The IP address of this container on the
                 network, using the IPv4 protocol. Defaults to ``None``.
             ipv6_address (str): The IP address of this container on the
                 network, using the IPv6 protocol. Defaults to ``None``.
-            link_local_ips (list): A list of link-local (IPv4/IPv6)
+            link_local_ips (:py:class:`list`): A list of link-local (IPv4/IPv6)
                 addresses.
 
         Returns:
diff --git a/docker/api/network.py b/docker/api/network.py
index 7ccda55..9f6d98f 100644
--- a/docker/api/network.py
+++ b/docker/api/network.py
@@ -11,13 +11,13 @@ class NetworkApiMixin(object):
         List networks. Similar to the ``docker networks ls`` command.
 
         Args:
-            names (list): List of names to filter by
-            ids (list): List of ids to filter by
+            names (:py:class:`list`): List of names to filter by
+            ids (:py:class:`list`): List of ids to filter by
             filters (dict): Filters to be processed on the network list.
                 Available filters:
                 - ``driver=[<driver-name>]`` Matches a network's driver.
                 - ``label=[<key>]`` or ``label=[<key>=<value>]``.
-                - ``type=["custom"|"builtin"] `` Filters networks by type.
+                - ``type=["custom"|"builtin"]`` Filters networks by type.
 
         Returns:
             (dict): List of network objects.
@@ -169,17 +169,18 @@ class NetworkApiMixin(object):
         Args:
             container (str): container-id/name to be connected to the network
             net_id (str): network id
-            aliases (list): A list of aliases for this endpoint. Names in that
-                list can be used within the network to reach the container.
-                Defaults to ``None``.
-            links (list): A list of links for this endpoint. Containers
-                declared in this list will be linkedto this container.
-                Defaults to ``None``.
+            aliases (:py:class:`list`): A list of aliases for this endpoint.
+                Names in that list can be used within the network to reach the
+                container. Defaults to ``None``.
+            links (:py:class:`list`): A list of links for this endpoint.
+                Containers declared in this list will be linked to this
+                container. Defaults to ``None``.
             ipv4_address (str): The IP address of this container on the
                 network, using the IPv4 protocol. Defaults to ``None``.
             ipv6_address (str): The IP address of this container on the
                 network, using the IPv6 protocol. Defaults to ``None``.
-            link_local_ips (list): A list of link-local (IPv4/IPv6) addresses.
+            link_local_ips (:py:class:`list`): A list of link-local
+            (IPv4/IPv6) addresses.
         """
         data = {
             "Container": container,
diff --git a/docker/api/service.py b/docker/api/service.py
index 7708b75..0d8421e 100644
--- a/docker/api/service.py
+++ b/docker/api/service.py
@@ -13,18 +13,18 @@ class ServiceApiMixin(object):
         Create a service.
 
         Args:
-            task_template (dict): Specification of the task to start as part
-                of the new service.
+            task_template (TaskTemplate): Specification of the task to start as
+                part of the new service.
             name (string): User-defined name for the service. Optional.
             labels (dict): A map of labels to associate with the service.
                 Optional.
             mode (string): Scheduling mode for the service (``replicated`` or
                 ``global``). Defaults to ``replicated``.
-            update_config (dict): Specification for the update strategy of the
-                service. Default: ``None``
-            networks (list): List of network names or IDs to attach the
-                service to. Default: ``None``.
-            endpoint_config (dict): Properties that can be configured to
+            update_config (UpdateConfig): Specification for the update strategy
+                of the service. Default: ``None``
+            networks (:py:class:`list`): List of network names or IDs to attach
+                the service to. Default: ``None``.
+            endpoint_spec (EndpointSpec): Properties that can be configured to
                 access and load balance a service. Default: ``None``.
 
         Returns:
@@ -159,7 +159,7 @@ class ServiceApiMixin(object):
                 ``label`` and ``desired-state``.
 
         Returns:
-            (list): List of task dictionaries.
+            (:py:class:`list`): List of task dictionaries.
 
         Raises:
             :py:class:`docker.errors.APIError`
@@ -186,20 +186,18 @@ class ServiceApiMixin(object):
                 ID).
             version (int): The version number of the service object being
                 updated. This is required to avoid conflicting writes.
-            task_template (dict): Specification of the updated task to start
-                as part of the service. See the [TaskTemplate
-                class](#TaskTemplate) for details.
+            task_template (TaskTemplate): Specification of the updated task to
+                start as part of the service.
             name (string): New name for the service. Optional.
             labels (dict): A map of labels to associate with the service.
                 Optional.
             mode (string): Scheduling mode for the service (``replicated`` or
                 ``global``). Defaults to ``replicated``.
-            update_config (dict): Specification for the update strategy of the
-                service. See the [UpdateConfig class](#UpdateConfig) for
-                details. Default: ``None``.
-            networks (list): List of network names or IDs to attach the
-                service to. Default: ``None``.
-            endpoint_config (dict): Properties that can be configured to
+            update_config (UpdateConfig): Specification for the update strategy
+                of the service. Default: ``None``.
+            networks (:py:class:`list`): List of network names or IDs to attach
+                the service to. Default: ``None``.
+            endpoint_spec (EndpointSpec): Properties that can be configured to
                 access and load balance a service. Default: ``None``.
 
         Returns:
diff --git a/docker/api/swarm.py b/docker/api/swarm.py
index 3ada538..8877056 100644
--- a/docker/api/swarm.py
+++ b/docker/api/swarm.py
@@ -143,8 +143,8 @@ class SwarmApiMixin(object):
         Make this Engine join a swarm that has already been created.
 
         Args:
-            remote_addrs (list): Addresses of one or more manager nodes already
-                participating in the Swarm to join.
+            remote_addrs (:py:class:`list`): Addresses of one or more manager
+                nodes already participating in the Swarm to join.
             join_token (string): Secret token for joining this Swarm.
             listen_addr (string): Listen address used for inter-manager
                 communication if the node gets promoted to manager, as well as
diff --git a/docker/models/containers.py b/docker/models/containers.py
index ad1cb61..b1cdd8f 100644
--- a/docker/models/containers.py
+++ b/docker/models/containers.py
@@ -468,17 +468,17 @@ class ContainerCollection(Collection):
             device_write_bps: Limit write rate (bytes per second) from a
                 device.
             device_write_iops: Limit write rate (IO per second) from a device.
-            devices (list): Expose host devices to the container, as a list
-                of strings in the form
+            devices (:py:class:`list`): Expose host devices to the container,
+                as a list of strings in the form
                 ``<path_on_host>:<path_in_container>:<cgroup_permissions>``.
 
                 For example, ``/dev/sda:/dev/xvda:rwm`` allows the container
                 to have read-write access to the host's ``/dev/sda`` via a
                 node named ``/dev/xvda`` inside the container.
-            dns (list): Set custom DNS servers.
-            dns_opt (list): Additional options to be added to the container's
-                ``resolv.conf`` file.
-            dns_search (list): DNS search domains.
+            dns (:py:class:`list`): Set custom DNS servers.
+            dns_opt (:py:class:`list`): Additional options to be added to the
+                container's ``resolv.conf`` file.
+            dns_search (:py:class:`list`): DNS search domains.
             domainname (str or list): Set custom DNS search domains.
             entrypoint (str or list): The entrypoint for the container.
             environment (dict or list): Environment variables to set inside
@@ -486,8 +486,8 @@ class ContainerCollection(Collection):
                 format ``["SOMEVARIABLE=xxx"]``.
             extra_hosts (dict): Addtional hostnames to resolve inside the
                 container, as a mapping of hostname to IP address.
-            group_add (list): List of additional group names and/or IDs that
-                the container process will run as.
+            group_add (:py:class:`list`): List of additional group names and/or
+                IDs that the container process will run as.
             hostname (str): Optional hostname for the container.
             ipc_mode (str): Set the IPC mode for the container.
             isolation (str): Isolation technology to use. Default: `None`.
@@ -517,8 +517,8 @@ class ContainerCollection(Collection):
                 behavior. Accepts number between 0 and 100.
             memswap_limit (str or int): Maximum amount of memory + swap a
                 container is allowed to consume.
-            networks (list): A list of network names to connect this
-                container to.
+            networks (:py:class:`list`): A list of network names to connect
+                this container to.
             name (str): The name for this container.
             network_disabled (bool): Disable networking.
             network_mode (str): One of:
@@ -574,8 +574,8 @@ class ContainerCollection(Collection):
                 For example:
                 ``{"Name": "on-failure", "MaximumRetryCount": 5}``
 
-            security_opt (list): A list of string values to customize labels
-                for MLS systems, such as SELinux.
+            security_opt (:py:class:`list`): A list of string values to
+                customize labels for MLS systems, such as SELinux.
             shm_size (str or int): Size of /dev/shm (e.g. ``1G``).
             stdin_open (bool): Keep ``STDIN`` open even if not attached.
             stdout (bool): Return logs from ``STDOUT`` when ``detach=False``.
@@ -598,8 +598,8 @@ class ContainerCollection(Collection):
                     }
 
             tty (bool): Allocate a pseudo-TTY.
-            ulimits (list): Ulimits to set inside the container, as a list of
-                dicts.
+            ulimits (:py:class:`list`): Ulimits to set inside the container, as
+                a list of dicts.
             user (str or int): Username or UID to run commands as inside the
                 container.
             userns_mode (str): Sets the user namespace mode for the container
@@ -621,8 +621,8 @@ class ContainerCollection(Collection):
                     {'/home/user1/': {'bind': '/mnt/vol2', 'mode': 'rw'},
                      '/var/www': {'bind': '/mnt/vol1', 'mode': 'ro'}}
 
-            volumes_from (list): List of container names or IDs to get
-                volumes from.
+            volumes_from (:py:class:`list`): List of container names or IDs to
+                get volumes from.
             working_dir (str): Path to the working directory.
 
         Returns:
diff --git a/docker/models/networks.py b/docker/models/networks.py
index d5e2097..a80c9f5 100644
--- a/docker/models/networks.py
+++ b/docker/models/networks.py
@@ -32,17 +32,18 @@ class Network(Model):
             container (str): Container to connect to this network, as either
                 an ID, name, or :py:class:`~docker.models.containers.Container`
                 object.
-            aliases (list): A list of aliases for this endpoint. Names in that
-                list can be used within the network to reach the container.
-                Defaults to ``None``.
-            links (list): A list of links for this endpoint. Containers
-                declared in this list will be linkedto this container.
-                Defaults to ``None``.
+            aliases (:py:class:`list`): A list of aliases for this endpoint.
+                Names in that list can be used within the network to reach the
+                container. Defaults to ``None``.
+            links (:py:class:`list`): A list of links for this endpoint.
+                Containers declared in this list will be linkedto this
+                container. Defaults to ``None``.
             ipv4_address (str): The IP address of this container on the
                 network, using the IPv4 protocol. Defaults to ``None``.
             ipv6_address (str): The IP address of this container on the
                 network, using the IPv6 protocol. Defaults to ``None``.
-            link_local_ips (list): A list of link-local (IPv4/IPv6) addresses.
+            link_local_ips (:py:class:`list`): A list of link-local (IPv4/IPv6)
+                addresses.
 
         Raises:
             :py:class:`docker.errors.APIError`
@@ -167,8 +168,8 @@ class NetworkCollection(Collection):
         List networks. Similar to the ``docker networks ls`` command.
 
         Args:
-            names (list): List of names to filter by.
-            ids (list): List of ids to filter by.
+            names (:py:class:`list`): List of names to filter by.
+            ids (:py:class:`list`): List of ids to filter by.
 
         Returns:
             (list of :py:class:`Network`) The networks on the server.
diff --git a/docker/models/services.py b/docker/models/services.py
index d70c9e7..ef6c3e3 100644
--- a/docker/models/services.py
+++ b/docker/models/services.py
@@ -42,7 +42,7 @@ class Service(Model):
                 ``label``, and ``desired-state``.
 
         Returns:
-            (list): List of task dictionaries.
+            (:py:class:`list`): List of task dictionaries.
 
         Raises:
             :py:class:`docker.errors.APIError`
@@ -92,29 +92,27 @@ class ServiceCollection(Collection):
             args (list of str): Arguments to the command.
             constraints (list of str): Placement constraints.
             container_labels (dict): Labels to apply to the container.
-            endpoint_spec (dict): Properties that can be configured to
+            endpoint_spec (EndpointSpec): Properties that can be configured to
                 access and load balance a service. Default: ``None``.
             env (list of str): Environment variables, in the form
                 ``KEY=val``.
             labels (dict): Labels to apply to the service.
             log_driver (str): Log driver to use for containers.
             log_driver_options (dict): Log driver options.
-            mode (string): Scheduling mode for the service (``replicated`` or
+            mode (str): Scheduling mode for the service (``replicated`` or
                 ``global``). Defaults to ``replicated``.
             mounts (list of str): Mounts for the containers, in the form
                 ``source:target:options``, where options is either
                 ``ro`` or ``rw``.
             name (str): Name to give to the service.
-            networks (list): List of network names or IDs to attach the
-                service to. Default: ``None``.
-            resources (dict): Resource limits and reservations. For the
-                format, see the Remote API documentation.
-            restart_policy (dict): Restart policy for containers. For the
-                format, see the Remote API documentation.
+            networks (list of str): List of network names or IDs to attach
+                the service to. Default: ``None``.
+            resources (Resources): Resource limits and reservations.
+            restart_policy (RestartPolicy): Restart policy for containers.
             stop_grace_period (int): Amount of time to wait for
                 containers to terminate before forcefully killing them.
-            update_config (dict): Specification for the update strategy of the
-                service. Default: ``None``
+            update_config (UpdateConfig): Specification for the update strategy
+                of the service. Default: ``None``
             user (str): User to run commands as.
             workdir (str): Working directory for commands to run.
 
diff --git a/docker/types/networks.py b/docker/types/networks.py
index 628ea65..1c7b2c9 100644
--- a/docker/types/networks.py
+++ b/docker/types/networks.py
@@ -48,7 +48,7 @@ class IPAMConfig(dict):
     Args:
 
         driver (str): The IPAM driver to use. Defaults to ``default``.
-        pool_configs (list): A list of pool configurations
+        pool_configs (:py:class:`list`): A list of pool configurations
           (:py:class:`~docker.types.IPAMPool`). Defaults to empty list.
         options (dict): Driver options as a key-value dictionary.
           Defaults to `None`.
diff --git a/docker/types/services.py b/docker/types/services.py
index 93503dc..6e1ad32 100644
--- a/docker/types/services.py
+++ b/docker/types/services.py
@@ -20,7 +20,7 @@ class TaskTemplate(dict):
           individual container created as part of the service.
         restart_policy (RestartPolicy): Specification for the restart policy
           which applies to containers created as part of this service.
-        placement (list): A list of constraints.
+        placement (:py:class:`list`): A list of constraints.
     """
     def __init__(self, container_spec, resources=None, restart_policy=None,
                  placement=None, log_driver=None):
@@ -62,16 +62,16 @@ class ContainerSpec(dict):
 
         image (string): The image name to use for the container.
         command (string or list):  The command to be run in the image.
-        args (list): Arguments to the command.
+        args (:py:class:`list`): Arguments to the command.
         env (dict): Environment variables.
         dir (string): The working directory for commands to run in.
         user (string): The user inside the container.
         labels (dict): A map of labels to associate with the service.
-        mounts (list): A list of specifications for mounts to be added to
-          containers created as part of the service. See the
-          :py:class:`~docker.types.Mount` class for details.
+        mounts (:py:class:`list`): A list of specifications for mounts to be
+            added to containers created as part of the service. See the
+            :py:class:`~docker.types.Mount` class for details.
         stop_grace_period (int): Amount of time to wait for the container to
-          terminate before forcefully killing it.
+            terminate before forcefully killing it.
     """
     def __init__(self, image, command=None, args=None, env=None, workdir=None,
                  user=None, labels=None, mounts=None, stop_grace_period=None):
@@ -106,7 +106,7 @@ class ContainerSpec(dict):
 class Mount(dict):
     """
     Describes a mounted folder's configuration inside a container. A list of
-    ``Mount``s would be used as part of a
+    :py:class:`Mount`s would be used as part of a
     :py:class:`~docker.types.ContainerSpec`.
 
     Args:
diff --git a/docs/api.rst b/docs/api.rst
index 5e59aa7..110b0a7 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -19,8 +19,6 @@ Containers
   :members:
   :undoc-members:
 
-.. py:module:: docker.api.image
-
 Images
 ------
 
diff --git a/docs/index.rst b/docs/index.rst
index 67dd33f..8a86cc6 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -73,13 +73,12 @@ You can manage images:
   >>> client.images.list()
   [<Image 'ubuntu'>, <Image 'nginx'>, ...]
 
-That's just a taster of what you can do with the Docker SDK for Python. For more, :doc:`take a look at the reference <client>`.
+That's just a taste of what you can do with the Docker SDK for Python. For more, :doc:`take a look at the reference <client>`.
 
 .. toctree::
   :hidden:
   :maxdepth: 2
 
-  Home <index>
   client
   containers
   images