Move exec_run example to user guides section of docs

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

5 files changed, 79 insertions, 64 deletions

diff --git a/docker/models/containers.py b/docker/models/containers.py
index 75d8c2e..41bc4da 100644
--- a/docker/models/containers.py
+++ b/docker/models/containers.py
@@ -181,70 +181,6 @@ class Container(Model):
         Raises:
             :py:class:`docker.errors.APIError`
                 If the server returns an error.
-
-        Example:
-
-            Create a container that runs in the background
-
-            >>> client = docker.from_env()
-            >>> container = client.containers.run(
-            ...     'bfirsh/reticulate-splines', detach=True)
-
-            Prepare the command we are going to use. It prints "hello stdout"
-            in `stdout`, followed by "hello stderr" in `stderr`:
-
-            >>> cmd = '/bin/sh -c "echo hello stdout ; echo hello stderr >&2"'
-
-            We'll run this command with all four the combinations of ``stream``
-            and ``demux``.
-
-            With ``stream=False`` and ``demux=False``, the output is a string
-            that contains both the `stdout` and the `stderr` output:
-
-            >>> res = container.exec_run(cmd, stream=False, demux=False)
-            >>> res.output
-            b'hello stderr\nhello stdout\n'
-
-            With ``stream=True``, and ``demux=False``, the output is a
-            generator that yields strings containing the output of both
-            `stdout` and `stderr`:
-
-            >>> res = container.exec_run(cmd, stream=True, demux=False)
-            >>> next(res.output)
-            b'hello stdout\n'
-            >>> next(res.output)
-            b'hello stderr\n'
-            >>> next(res.output)
-            Traceback (most recent call last):
-              File "<stdin>", line 1, in <module>
-            StopIteration
-
-            With ``stream=True`` and ``demux=True``, the generator now
-            separates the streams, and yield tuples
-            ``(stdout, stderr)``:
-
-            >>> res = container.exec_run(cmd, stream=True, demux=True)
-            >>> next(res.output)
-            (b'hello stdout\n', None)
-            >>> next(res.output)
-            (None, b'hello stderr\n')
-            >>> next(res.output)
-            Traceback (most recent call last):
-              File "<stdin>", line 1, in <module>
-            StopIteration
-
-            Finally, with ``stream=False`` and ``demux=True``, the whole output
-            is returned, but the streams are still separated:
-
-            >>> res = container.exec_run(cmd, stream=True, demux=True)
-            >>> next(res.output)
-            (b'hello stdout\n', None)
-            >>> next(res.output)
-            (None, b'hello stderr\n')
-            >>> next(res.output)
-            Traceback (most recent call last):
-              File "<stdin>", line 1, in <module>
-            StopIteration
         """
         resp = self.client.api.exec_create(
             self.id, cmd, stdout=stdout, stderr=stderr, stdin=stdin, tty=tty,
diff --git a/docs/index.rst b/docs/index.rst
index 39426b6..63e85d3 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -92,4 +92,5 @@ That's just a taste of what you can do with the Docker SDK for Python. For more,
   volumes
   api
   tls
+  user_guides/index
   change-log
diff --git a/docs/user_guides/index.rst b/docs/user_guides/index.rst
new file mode 100644
index 0000000..79b3a90
--- /dev/null
+++ b/docs/user_guides/index.rst
@@ -0,0 +1,8 @@
+User guides and tutorials
+=========================
+
+.. toctree::
+  :maxdepth: 2
+
+  multiplex
+  swarm_services
\ No newline at end of file
diff --git a/docs/user_guides/multiplex.rst b/docs/user_guides/multiplex.rst
new file mode 100644
index 0000000..78d7e37
--- /dev/null
+++ b/docs/user_guides/multiplex.rst
@@ -0,0 +1,66 @@
+Handling multiplexed streams
+============================
+
+.. note::
+      The following instruction assume you're interested in getting output from
+      an ``exec`` command. These instruction are similarly applicable to the
+      output of ``attach``.
+
+First create a container that runs in the background:
+
+>>> client = docker.from_env()
+>>> container = client.containers.run(
+...     'bfirsh/reticulate-splines', detach=True)
+
+Prepare the command we are going to use. It prints "hello stdout"
+in `stdout`, followed by "hello stderr" in `stderr`:
+
+>>> cmd = '/bin/sh -c "echo hello stdout ; echo hello stderr >&2"'
+We'll run this command with all four the combinations of ``stream``
+and ``demux``.
+With ``stream=False`` and ``demux=False``, the output is a string
+that contains both the `stdout` and the `stderr` output:
+>>> res = container.exec_run(cmd, stream=False, demux=False)
+>>> res.output
+b'hello stderr\nhello stdout\n'
+
+With ``stream=True``, and ``demux=False``, the output is a
+generator that yields strings containing the output of both
+`stdout` and `stderr`:
+
+>>> res = container.exec_run(cmd, stream=True, demux=False)
+>>> next(res.output)
+b'hello stdout\n'
+>>> next(res.output)
+b'hello stderr\n'
+>>> next(res.output)
+Traceback (most recent call last):
+  File "<stdin>", line 1, in <module>
+StopIteration
+
+With ``stream=True`` and ``demux=True``, the generator now
+separates the streams, and yield tuples
+``(stdout, stderr)``:
+
+>>> res = container.exec_run(cmd, stream=True, demux=True)
+>>> next(res.output)
+(b'hello stdout\n', None)
+>>> next(res.output)
+(None, b'hello stderr\n')
+>>> next(res.output)
+Traceback (most recent call last):
+  File "<stdin>", line 1, in <module>
+StopIteration
+
+Finally, with ``stream=False`` and ``demux=True``, the whole output
+is returned, but the streams are still separated:
+
+>>> res = container.exec_run(cmd, stream=True, demux=True)
+>>> next(res.output)
+(b'hello stdout\n', None)
+>>> next(res.output)
+(None, b'hello stderr\n')
+>>> next(res.output)
+Traceback (most recent call last):
+  File "<stdin>", line 1, in <module>
+StopIteration
diff --git a/docs/user_guides/swarm_services.md b/docs/user_guides/swarm_services.md
index 9bd4dca..369fbed 100644
--- a/docs/user_guides/swarm_services.md
+++ b/docs/user_guides/swarm_services.md
@@ -1,5 +1,9 @@
 # Swarm services
 
+>    Warning:
+>    This is a stale document and may contain outdated information.
+>    Refer to the API docs for updated classes and method signatures.
+
 Starting with Engine version 1.12 (API 1.24), it is possible to manage services
 using the Docker Engine API. Note that the engine needs to be part of a
 [Swarm cluster](../swarm.rst) before you can use the service-related methods.