README.md formatting changes

Signed-off-by: Maxime Petazzoni <max@signalfuse.com>

README.md

@@ -8,122 +8,225 @@ An API client for docker written in Python
 API
 ===
 
-`docker.Client(base_url='unix://var/run/docker.sock', version="1.4",
+To instantiate a `Client` class that will allow you to communicate with
-timeout=60)`  
+a Docker daemon, simply do:
-Client class. `base_url` refers to the protocol+hostname+port where the docker
-server is hosted. Version is the version of the API the client will use.
 
-* `c.build(path=None, tag=None, quiet=False, fileobj=None, nocache=False, rm=False)`  
+```python
-Similar to the `docker build` command. Either `path` or `fileobj` needs to be
+c = docker.Client(base_url='unix://var/run/docker.sock',
-set. `path` can be a local path (to a directory containing a Dockerfile) or a
+                  version='1.6',
-remote URL. `fileobj` must be a readable file-like object to a Dockerfile.
+                  timeout=10)
+```
+
+`base_url` refers to the protocol+hostname+port where the docker server
+is hosted. `version` is the version of the API the client will use and
+`timeout` specifies the HTTP request timeout, in seconds.
+
+```python
+c.build(path=None, tag=None, quiet=False, fileobj=None, nocache=False,
+        rm=False)
+```
+
+Similar to the `docker build` command. Either `path` or `fileobj` needs
+to be set. `path` can be a local path (to a directory containing a
+Dockerfile) or a remote URL. `fileobj` must be a readable file-like
+object to a Dockerfile.
+
+```python
+c.commit(container, repository=None, tag=None, message=None, author=None,
+         conf=None)
+```
 
-* `c.commit(container, repository=None, tag=None, message=None, author=None, conf=None)`  
 Identical to the `docker commit` command.
 
-* `c.containers(quiet=False, all=False, trunc=True, latest=False, since=None,before=None, limit=-1)`  
+```python
+c.containers(quiet=False, all=False, trunc=True, latest=False, since=None,
+             before=None, limit=-1)
+```
+
 Identical to the `docker ps` command.
 
-* `c.copy(container, resource)`  
+```python
+c.copy(container, resource)
+```
+
 Identical to the `docker cp` command.
 
-* <code>c.create_container(image, command=None, hostname=None, user=None,
+```python
-        detach=False, stdin_open=False, tty=False, mem_limit=0, ports=None, environment=None, dns=None, volumes=None, volumes_from=None, 
+c.create_container(image, command=None, hostname=None, user=None,
-        name=None)</code>  
+                   detach=False, stdin_open=False, tty=False, mem_limit=0,
-Creates a container that can then be `start`ed. Parameters are similar to those
+                   ports=None, environment=None, dns=None, volumes=None,
-for the `docker run` command except it doesn't support the attach options
+                   volumes_from=None, name=None)
-(`-a`)  
+```
-See "Port bindings" and "Using volumes" below for more information on how to
+
-create port bindings and volume mappings.
+Creates a container that can then be `start`ed. Parameters are similar
+to those for the `docker run` command except it doesn't support the
+attach options (`-a`). See "Port bindings" and "Using volumes" below for
+more information on how to create port bindings and volume mappings.
+
+```python
+c.diff(container)
+```
 
-* `c.diff(container)`  
 Identical to the `docker diff` command.
 
-* `c.export(container)`  
+```python
+c.export(container)
+```
+
 Identical to the `docker export` command.
 
-* `c.history(image)`  
+```python
+c.history(image)
+```
+
 Identical to the `docker history` command.
 
-* `c.images(name=None, quiet=False, all=False, viz=False)`  
+```python
+c.images(name=None, quiet=False, all=False, viz=False)
+```
+
 Identical to the `docker images` command.
 
-* `c.import_image(src, repository=None, tag=None)`  
+```python
-Identical to the `docker import` command. If `src` is a string or unicode
+c.import_image(src, repository=None, tag=None)
-string, it will be treated as a URL to fetch the image from. To import an image
+```
-from the local machine, `src` needs to be a file-like object or bytes
+
-collection.
+Identical to the `docker import` command. If `src` is a string or
-To import from a tarball use your absolute path to your tarball.
+unicode string, it will be treated as a URL to fetch the image from. To
-To load arbitrary data as tarball use whatever you want as src and your tarball content in data.
+import an image from the local machine, `src` needs to be a file-like
+object or bytes collection.  To import from a tarball use your absolute
+path to your tarball.  To load arbitrary data as tarball use whatever
+you want as src and your tarball content in data.
+
+```python
+c.info()
+```
 
-* `c.info()`  
 Identical to the `docker info` command.
 
-* `c.insert(url, path)`  
+```python
+c.insert(url, path)
+```
+
 Identical to the `docker insert` command.
 
-* `c.inspect_container(container)`  
+```python
+c.inspect_container(container)
+```
+
 Identical to the `docker inspect` command, but only for containers.
 
-* `c.inspect_image(image_id)`  
+```python
+c.inspect_image(image_id)
+```
+
 Identical to the `docker inspect` command, but only for images.
 
-* `c.kill(container, signal=None)`  
+```python
+c.kill(container, signal=None)
+```
+
 Kill a container. Similar to the `docker kill` command.
 
-* `c.login(username, password=None, email=None)`  
+```python
+c.login(username, password=None, email=None)
+```
+
 Identical to the `docker login` command (but non-interactive, obviously).
 
-* `c.logs(container)`  
+```python
-Identical to the `docker logs` command.
+c.logs(container, stdout=True, stderr=True, stream=False)
+```
+
+Identical to the `docker logs` command. The `stream` parameter makes the
+`logs` function return a blocking generator you can iterate over to
+retrieve log output as it happens.
+
+```python
+c.port(container, private_port)
+```
 
-* `c.port(container, private_port)`  
 Identical to the `docker port` command.
 
-* `c.pull(repository, tag=None)`
+```python
+c.pull(repository, tag=None)
+```
+
 Identical to the `docker pull` command.
 
-* `c.push(repository)`  
+```python
+c.push(repository)
+```
+
 Identical to the `docker push` command.
 
-* `c.remove_container(container, v=False)`  
+````python
+c.remove_container(container, v=False)
+```
+
 Remove a container. Similar to the `docker rm` command.
 
-* `c.remove_image(image)`  
+```python
+c.remove_image(image)
+```
+
 Remove an image. Similar to the `docker rmi` command.
 
-* `c.restart(container, timeout=10)`  
+```python
+c.restart(container, timeout=10)
+```
 Restart a container. Similar to the `docker restart` command.
 
-* `c.search(term)`  
+```python
+c.search(term)
+```
+
 Identical to the `docker search` command.
 
-* `c.start(container, binds=None, port_bindings=None, lxc_conf=None, privileged=False)`
+```python
-Similar to the `docker start` command, but doesn't support attach options.
+c.start(container, binds=None, port_bindings=None, lxc_conf=None,
-Use `docker logs` to recover `stdout`/`stderr`  
+        privileged=False)
-`binds` Allows to bind a directory in the host to the container. See 
+```
-"Using volumes" below for more information.
+
-`port_bindings` Exposes container ports to the host. See "Port bindings" below
+Similar to the `docker start` command, but doesn't support attach
-for more information.
+options.  Use `docker logs` to recover `stdout`/`stderr`.
-`lxc_conf` allows to pass LXC configuration options using a dictionary.
+
-`privileged` starts the container in privileged mode.
+`binds` allows to bind a directory in the host to the container. See
+"Using volumes" below for more information. `port_bindings` exposes
+container ports to the host. See "Port bindings" below for more
+information. `lxc_conf` allows to pass LXC configuration options using a
+dictionary. `privileged` starts the container in privileged mode.
+
+```python
+c.stop(container, timeout=10)
+```
 
-* `c.stop(container, timeout=10)`  
 Stops a container. Similar to the `docker stop` command.
 
-* `c.tag(image, repository, tag=None, force=False)`  
+```python
+c.tag(image, repository, tag=None, force=False)
+```
+
 Identical to the `docker tag` command.
 
-* `c.top(container_id)`  
+```python
+c.top(container_id)
+```
+
 Identical to the `docker top` command.
 
-* `c.version()`  
+```python
+c.version()
+```
+
 Identical to the `docker version` command.
 
-* `c.wait(container)`  
+```python
-Wait for a container and return its exit code. Similar to the `docker wait`
+c.wait(container)
-command.
+```
 
+Wait for a container and return its exit code. Similar to the `docker
+wait` command.
 
 
 Port bindings
@@ -132,31 +235,33 @@ Port bindings
 Port bindings is done in two parts. Firstly, by providing a list of ports to
 open inside the container in the `Client.create_container` method.
 
-    client.create_container('busybox', 'ls', ports=[1111, 2222])
+```python
+c.create_container('busybox', 'ls', ports=[1111, 2222])
+```
 
 If you wish to use UDP instead of TCP (default), you can declare it like such:
 
-    client.create_container('busybox', 'ls', ports=[(1111, 'udp'), 2222])
+```python
+c.create_container('busybox', 'ls', ports=[(1111, 'udp'), 2222])
+```
 
 Bindings are then declared in the `Client.start` method.
 
-    client.start(container_id, port_bindings={
+```python
-        1111: 4567,
+c.start(container_id, port_bindings={1111: 4567, 2222: None})
-        2222: None
+```
-    })
 
 You can limit the host address on which the port will be exposed like such:
 
-    client.start(container_id, port_bindings={
+```python
-        1111: ('127.0.0.1', 4567)
+c.start(container_id, port_bindings={1111: ('127.0.0.1', 4567)})
-    })
+```
 
-or without host port assignment:
+Or without host port assignment:
-
-    client.start(container_id, port_bindings={
-        1111: ('127.0.0.1',)
-    })
 
+```python
+c.start(container_id, port_bindings={1111: ('127.0.0.1',)})
+```
 
 
 Using volumes
@@ -165,11 +270,15 @@ Using volumes
 Similarly, volume declaration is done in two parts. First, you have to provide
 a list of mountpoints to the `Client.create_container` method.
 
-    client.create_container('busybox', 'ls', volumes=['/mnt/vol1', '/mnt/vol2'])
+```python
+c.create_container('busybox', 'ls', volumes=['/mnt/vol1', '/mnt/vol2'])
+```
 
 Volume mappings are then declared inside the `Client.start` method like this:
 
-    client.start(container_id, bindings={
+```python
-            '/mnt/vol2': '/home/user1/',
+c.start(container_id, bindings={
-            '/mnt/vol1': '/var/www'
+    '/mnt/vol2': '/home/user1/',
-    })
+    '/mnt/vol1': '/var/www'
+})
+```