Improve ulimits documentation

Signed-off-by: Joffrey F <joffrey@docker.com>

docker/api/container.py

@@ -543,7 +543,7 @@ class ContainerApiMixin(object):
                     }
 
             ulimits (:py:class:`list`): Ulimits to set inside the container,
-                as a list of dicts.
+                as a list of :py:class:`docker.types.Ulimit` instances.
             userns_mode (str): Sets the user namespace mode for the container
                 when user namespace remapping option is enabled. Supported
                 values are: ``host``

docker/models/containers.py

@@ -691,8 +691,8 @@ class ContainerCollection(Collection):
                     }
 
             tty (bool): Allocate a pseudo-TTY.
-            ulimits (:py:class:`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 :py:class:`docker.types.Ulimit` instances.
             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

docker/types/containers.py

@@ -58,6 +58,23 @@ class LogConfig(DictType):
 
 
 class Ulimit(DictType):
+    """
+    Create a ulimit declaration to be used with
+    :py:meth:`~docker.api.container.ContainerApiMixin.create_host_config`.
+
+    Args:
+
+        name (str): Which ulimit will this apply to. A list of valid names can
+            be found `here <http://tinyurl.me/ZWRkM2Ztwlykf>`_.
+        soft (int): The soft limit for this ulimit. Optional.
+        hard (int): The hard limit for this ulimit. Optional.
+
+    Example:
+
+        nproc_limit = docker.types.Ulimit(name='nproc', soft=1024)
+        hc = client.create_host_config(ulimits=[nproc_limit])
+        container = client.create_container('busybox', 'true', host_config=hc)
+    """
     def __init__(self, **kwargs):
         name = kwargs.get('name', kwargs.get('Name'))
         soft = kwargs.get('soft', kwargs.get('Soft'))

docs/api.rst

@@ -151,4 +151,5 @@ Configuration types
 .. autoclass:: SwarmExternalCA
 .. autoclass:: SwarmSpec(*args, **kwargs)
 .. autoclass:: TaskTemplate
+.. autoclass:: Ulimit
 .. autoclass:: UpdateConfig