From e34c0c9f06bd498d08218c300fc53497bf11720d Mon Sep 17 00:00:00 2001
From: Joshua Harlow <harlowja@yahoo-inc.com>
Date: Thu, 29 May 2014 15:37:04 -0700
Subject: [PATCH] Add docs related to the new conductor feature

Change-Id: I68722a5b6bea0e404427ec7b121e7c6f90e42145
---
 doc/source/conductors.rst | 44 +++++++++++++++++++++++++++++++++++++++
 doc/source/index.rst      | 21 ++++++++++++++++---
 doc/source/resumption.rst |  2 ++
 3 files changed, 64 insertions(+), 3 deletions(-)
 create mode 100644 doc/source/conductors.rst

diff --git a/doc/source/conductors.rst b/doc/source/conductors.rst
new file mode 100644
index 000000000..4dfa3e33f
--- /dev/null
+++ b/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
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 387980e4f..bb1b8b6b2 100644
--- a/doc/source/index.rst
+++ b/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
diff --git a/doc/source/resumption.rst b/doc/source/resumption.rst
index cc6e9eec3..120c16e30 100644
--- a/doc/source/resumption.rst
+++ b/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
 =========