Expand toctree to three levels

Three levels makes it easier to find content in the
main toctree so lets make it easier for folks to use
the table of contents to find what they are looking for
instead of making it harder...

This change makes three levels look readable as well as
fixes some discrepancies among the various sections...

Change-Id: I5fd7a062adec052c338790c9ba343dfbc51075e3

doc/source/arguments_and_results.rst

@@ -202,8 +202,11 @@ desirable to make those results accessible to others. To accomplish this
 the task/retry specifies names of those values via its ``provides`` constructor
 parameter or by its default provides attribute.
 
+Examples
+--------
+
 Returning one value
--------------------
++++++++++++++++++++
 
 If task returns just one value, ``provides`` should be string -- the
 name of the value.
@@ -218,7 +221,7 @@ name of the value.
     set(['the_answer'])
 
 Returning a tuple
------------------
++++++++++++++++++
 
 For a task that returns several values, one option (as usual in python) is to
 return those values via a ``tuple``.
@@ -258,7 +261,7 @@ and passed to the task |task.revert| or retry |retry.revert| method).
     :py:class:`~taskflow.exceptions.NotFound`  exception is raised.
 
 Returning a dictionary
-----------------------
+++++++++++++++++++++++
 
 Another option is to return several values as a dictionary (aka a ``dict``).
 
@@ -300,7 +303,7 @@ will be able to get elements from storage by name:
     exception is raised.
 
 Default provides
-----------------
+++++++++++++++++
 
 As mentioned above, the default base class provides nothing, which means
 results are not accessible to other tasks/retrys in the flow.

doc/source/atoms.rst

@@ -94,8 +94,8 @@ subclasses are provided:
   :py:class:`~taskflow.retry.ForEach` but extracts values from storage
   instead of the :py:class:`~taskflow.retry.ForEach` constructor.
 
-Usage
+Examples
------
+--------
 
 .. testsetup::
 

doc/source/engines.rst

@@ -135,8 +135,11 @@ the ``engine_conf`` parameter any helper factory function accepts. It may be:
 * A dictionary, naming engine type with key ``'engine'`` and possibly
   type-specific engine configuration parameters.
 
-Single-Threaded
+Types
----------------
+=====
+
+Serial
+------
 
 **Engine type**: ``'serial'``
 
@@ -180,7 +183,7 @@ Additional supported keyword arguments:
 
     Running tasks with a `process pool executor`_ is not currently supported.
 
-Worker-Based
+Worker-based
 ------------
 
 **Engine type**: ``'worker-based'``

doc/source/index.rst

@@ -14,7 +14,7 @@ Contents
 ========
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
    atoms
    arguments_and_results

doc/source/jobs.rst

@@ -161,6 +161,9 @@ might look like:
         time.sleep(coffee_break_time)
     ...
 
+Types
+=====
+
 Zookeeper
 ---------
 
@@ -248,6 +251,14 @@ Interfaces
 .. automodule:: taskflow.jobs.job
 .. automodule:: taskflow.jobs.jobboard
 
+Hierarchy
+=========
+
+.. inheritance-diagram::
+    taskflow.jobs.jobboard
+    taskflow.jobs.backends.impl_zookeeper
+    :parts: 1
+
 .. _paradigm shift: https://wiki.openstack.org/wiki/TaskFlow/Paradigm_shifts#Workflow_ownership_transfer
 .. _zookeeper: http://zookeeper.apache.org/
 .. _kazoo: http://kazoo.readthedocs.org/

doc/source/persistence.rst

@@ -144,6 +144,9 @@ the following:
   ``'connection'`` and possibly type-specific backend parameters as other
   keys.
 
+Types
+=====
+
 Memory
 ------
 

doc/source/resumption.rst

@@ -88,7 +88,7 @@ The following scenarios explain some expected structural changes and how they
 can be accommodated (and what the effect will be when resuming & running).
 
 Same atoms
-----------
+++++++++++
 
 When the factory function mentioned above returns the exact same the flow and
 atoms (no changes are performed).
@@ -98,7 +98,7 @@ atoms with :py:class:`~taskflow.persistence.logbook.AtomDetail` objects by name
 and then the engine resumes.
 
 Atom was added
---------------
+++++++++++++++
 
 When the factory function mentioned above alters the flow by adding a new atom
 in (for example for changing the runtime structure of what was previously ran
@@ -109,7 +109,7 @@ corresponding :py:class:`~taskflow.persistence.logbook.AtomDetail` does not
 exist and one will be created and associated.
 
 Atom was removed
-----------------
+++++++++++++++++
 
 When the factory function mentioned above alters the flow by removing a new
 atom in (for example for changing the runtime structure of what was previously
@@ -121,7 +121,7 @@ it was not there, and any results it returned if it was completed before will
 be ignored.
 
 Atom code was changed
----------------------
++++++++++++++++++++++
 
 When the factory function mentioned above alters the flow by deciding that a
 newer version of a previously existing atom should be ran (possibly to perform
@@ -137,8 +137,8 @@ ability to upgrade atoms before running (manual introspection & modification of
 a :py:class:`~taskflow.persistence.logbook.LogBook` can be done before engine
 loading and running to accomplish this in the meantime).
 
-Atom was split in two atoms or merged from two (or more) to one atom
+Atom was split in two atoms or merged
---------------------------------------------------------------------
++++++++++++++++++++++++++++++++++++++
 
 When the factory function mentioned above alters the flow by deciding that a
 previously existing atom should be split into N atoms or the factory function
@@ -154,7 +154,7 @@ introspection & modification of a
 loading and running to accomplish this in the meantime).
 
 Flow structure was changed
---------------------------
+++++++++++++++++++++++++++
 
 If manual links were added or removed from graph, or task requirements were
 changed, or flow was refactored (atom moved into or out of subflows, linear