Make the examples documentation more relevant

Instead of just linking to the examples source tree
provide a list of recommended examples (in order of
my perceived complexity) that can help new comers
view examples in a more organized and relevant manner.

Change-Id: I9f6d15fb042e3fe67fd29a9c331fc779c254241c

doc/source/examples.rst

@@ -1,11 +1,98 @@
-========
-Examples
-========
+Linear phone calls
+==================
 
-While developing TaskFlow the team has worked hard to make sure the concepts
-that TaskFlow provides are explained by *relevant* examples. To explore these
-please check out the `examples`_ directory in the TaskFlow source tree. If the
-examples provided are not satisfactory (or up to your standards) contributions
-are welcome and very much appreciated to improve them.
+.. literalinclude:: ../../taskflow/examples/simple_linear.py
+    :language: python
+    :linenos:
+    :lines: 16-
+    :emphasize-lines: 16-28
 
-.. _examples: http://git.openstack.org/cgit/openstack/taskflow/tree/taskflow/examples
+Linear phone calls (reverting)
+==============================
+
+.. literalinclude:: ../../taskflow/examples/reverting_linear.py
+    :language: python
+    :linenos:
+    :lines: 16-
+    :emphasize-lines: 17-32
+
+Building a car
+==============
+
+.. literalinclude:: ../../taskflow/examples/build_a_car.py
+    :language: python
+    :linenos:
+    :lines: 16-
+    :emphasize-lines: 20-26
+
+Task dependencies
+=================
+
+.. literalinclude:: ../../taskflow/examples/graph_flow.py
+    :language: python
+    :linenos:
+    :lines: 16-
+    :emphasize-lines: 18-31
+
+Parallel calculations
+=====================
+
+.. literalinclude:: ../../taskflow/examples/calculate_in_parallel.py
+    :language: python
+    :linenos:
+    :lines: 16-
+    :emphasize-lines: 18-21
+
+Parallel pseudo-volume-create
+=============================
+
+.. literalinclude:: ../../taskflow/examples/create_parallel_volume.py
+    :language: python
+    :linenos:
+    :lines: 16-
+    :emphasize-lines: 21-23
+
+Suspended workflow reloaded
+===========================
+
+.. literalinclude:: ../../taskflow/examples/resume_from_backend.py
+    :language: python
+    :linenos:
+    :lines: 16-
+    :emphasize-lines: 22-39
+
+Resumable vm-pseudo-boot
+========================
+
+.. literalinclude:: ../../taskflow/examples/resume_vm_boot.py
+    :language: python
+    :linenos:
+    :lines: 16-
+    :emphasize-lines: 32-34
+
+Resumable volume-pseudo-create
+==============================
+
+.. literalinclude:: ../../taskflow/examples/resume_volume_create.py
+    :language: python
+    :linenos:
+    :lines: 16-
+    :emphasize-lines: 28-30
+
+Running engines by iteration
+============================
+
+.. literalinclude:: ../../taskflow/examples/run_by_iter.py
+    :language: python
+    :linenos:
+    :lines: 16-
+    :emphasize-lines: 24-27
+
+Retry controlling
+=================
+
+.. literalinclude:: ../../taskflow/examples/retry_flow.py
+    :language: python
+    :linenos:
+    :lines: 16-
+    :emphasize-lines: 17-25

doc/source/index.rst

@@ -34,6 +34,31 @@ Contents
 
    workers
 
+Examples
+--------
+
+While developing TaskFlow the team has worked *hard* to make sure the various
+concepts are explained by *relevant* examples. Here are a few selected examples
+to get started (ordered by *perceived* complexity):
+
+.. toctree::
+   :maxdepth: 2
+
+   examples
+
+To explore more of these examples please check out the `examples`_ directory
+in the TaskFlow `source tree`_.
+
+.. note::
+
+    If the examples provided are not satisfactory (or up to your
+    standards) contributions are welcome and very much appreciated to help
+    improve them. The higher the quality and the clearer the examples are the
+    better and more useful they are for everyone.
+
+.. _examples: http://git.openstack.org/cgit/openstack/taskflow/tree/taskflow/examples
+.. _source tree: http://git.openstack.org/cgit/openstack/taskflow/
+
 Considerations
 --------------
 
@@ -66,7 +91,6 @@ Miscellaneous
 
    exceptions
    states
-   examples
 
 Indices and tables
 ==================