Improved LogConfig documentation

Signed-off-by: Joffrey F <[email protected]>

Author: shin-

docker/api/container.py

@@ -476,13 +476,7 @@ def create_host_config(self, *args, **kwargs):
             isolation (str): Isolation technology to use. Default: `None`.
             links (dict or list of tuples): Either a dictionary mapping name
                 to alias or as a list of ``(name, alias)`` tuples.
-            log_config (dict): Logging configuration, as a dictionary with
-                keys:
-
-                - ``type`` The logging driver name.
-                - ``config`` A dictionary of configuration for the logging
-                  driver.
-
+            log_config (LogConfig): Logging configuration
             lxc_conf (dict): LXC config.
             mem_limit (float or str): Memory limit. Accepts float values
                 (which represent the memory limit of the created container in

docker/models/containers.py

@@ -576,13 +576,7 @@ def run(self, image, command=None, stdout=True, stderr=False,
                 ``["label1", "label2"]``)
             links (dict or list of tuples): Either a dictionary mapping name
                 to alias or as a list of ``(name, alias)`` tuples.
-            log_config (dict): Logging configuration, as a dictionary with
-                keys:
-
-                - ``type`` The logging driver name.
-                - ``config`` A dictionary of configuration for the logging
-                  driver.
-
+            log_config (LogConfig): Logging configuration.
             mac_address (str): MAC address to assign to the container.
             mem_limit (int or str): Memory limit. Accepts float values
                 (which represent the memory limit of the created container in

docker/types/containers.py

@@ -23,6 +23,36 @@ class LogConfigTypesEnum(object):
 
 
 class LogConfig(DictType):
+    """
+    Configure logging for a container, when provided as an argument to
+    :py:meth:`~docker.api.container.ContainerApiMixin.create_host_config`.
+    You may refer to the
+    `official logging driver documentation <https://docs.docker.com/config/containers/logging/configure/>`_
+    for more information.
+
+    Args:
+        type (str): Indicate which log driver to use. A set of valid drivers
+            is provided as part of the :py:attr:`LogConfig.types`
+            enum. Other values may be accepted depending on the engine version
+            and available logging plugins.
+        config (dict): A driver-dependent configuration dictionary. Please
+            refer to the driver's documentation for a list of valid config
+            keys.
+
+    Example:
+
+        >>> from docker.types import LogConfig
+        >>> lc = LogConfig(type=LogConfig.types.JSON, config={
+        ...   'max-size': '1g',
+        ...   'labels': 'production_status,geo'
+        ... })
+        >>> hc = client.create_host_config(log_config=lc)
+        >>> container = client.create_container('busybox', 'true',
+        ...    host_config=hc)
+        >>> client.inspect_container(container)['HostConfig']['LogConfig']
+        {'Type': 'json-file', 'Config': {'labels': 'production_status,geo', 'max-size': '1g'}}
+
+    """ # flake8: noqa
     types = LogConfigTypesEnum
 
     def __init__(self, **kwargs):
@@ -50,9 +80,13 @@ def config(self):
         return self['Config']
 
     def set_config_value(self, key, value):
+        """ Set a the value for ``key`` to ``value`` inside the ``config``
+            dict.
+        """
         self.config[key] = value
 
     def unset_config(self, key):
+        """ Remove the ``key`` property from the ``config`` dict. """
         if key in self.config:
             del self.config[key]
 
@@ -71,9 +105,14 @@ class Ulimit(DictType):
 
     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)
+        >>> 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
+            )
+        >>> client.inspect_container(container)['HostConfig']['Ulimits']
+        [{'Name': 'nproc', 'Hard': 0, 'Soft': 1024}]
+
     """
     def __init__(self, **kwargs):
         name = kwargs.get('name', kwargs.get('Name'))

docs/api.rst

@@ -140,6 +140,7 @@ Configuration types
 .. autoclass:: Healthcheck
 .. autoclass:: IPAMConfig
 .. autoclass:: IPAMPool
+.. autoclass:: LogConfig
 .. autoclass:: Mount
 .. autoclass:: Placement
 .. autoclass:: Privileges