Merge "Expand toctree to three levels"

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