Merge "Add docs related to the new conductor feature"

doc/source/conductors.rst

@@ -0,0 +1,44 @@
+----------
+Conductors
+----------
+
+Overview
+========
+
+Conductors in TaskFlow provide a mechanism that unifies the various TaskFlow
+concepts under a single easy to use (as plug-and-play as we can make it)
+construct.
+
+They are responsible for the following:
+
+* Interacting with :doc:`jobboards <jobs>` (examining and claiming
+  :doc:`jobs <jobs>`).
+* Creating :doc:`engines <engines>` from the claimed jobs (using
+  :ref:`factories <resumption factories>` to reconstruct the contained
+  tasks and flows to be executed).
+* Dispatching the engine using the provided :doc:`persistence <persistence>`
+  layer and engine configuration.
+* Completing or abandoning the claimed job (depending on dispatching and
+  execution outcome).
+* *Rinse and repeat*.
+
+.. note::
+
+     They are inspired by and have similar responsiblities
+     as `railroad conductors`_.
+
+Interfaces
+==========
+
+.. automodule:: taskflow.conductors.base
+.. automodule:: taskflow.conductors.single_threaded
+
+Hierarchy
+=========
+
+.. inheritance-diagram::
+    taskflow.conductors.base
+    taskflow.conductors.single_threaded
+    :parts: 1
+
+.. _railroad conductors: http://en.wikipedia.org/wiki/Conductor_%28transportation%29

doc/source/index.rst

@@ -11,19 +11,34 @@ easy, consistent, and reliable.*
 
 Contents
 ========
+
 .. toctree::
    :maxdepth: 2
 
    atoms
    arguments_and_results
+   inputs_and_outputs
+
    patterns
    engines
-   workers
-   jobs
-   inputs_and_outputs
    notifications
    persistence
    resumption
+
+   jobs
+   conductors
+
+.. toctree::
+   :hidden:
+
+   workers
+
+Miscellaneous
+-------------
+
+.. toctree::
+   :maxdepth: 2
+
    exceptions
    utils
    states

doc/source/resumption.rst

@@ -19,6 +19,8 @@ in order to revert those atoms or resume those atoms in the correct ordering.
 TaskFlow provides a pattern that can help in automating this process (it does
 **not** prohibit the user from creating their own strategies for doing this).
 
+.. _resumption factories:
+
 Factories
 =========