From b5e3fbebc6ea35f6e90936fbfed1c198e1045314 Mon Sep 17 00:00:00 2001 From: Joshua Harlow Date: Sat, 20 Sep 2014 10:40:35 -0700 Subject: [PATCH] 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 | 11 +++++++---- doc/source/atoms.rst | 4 ++-- doc/source/engines.rst | 9 ++++++--- doc/source/index.rst | 2 +- doc/source/jobs.rst | 11 +++++++++++ doc/source/persistence.rst | 3 +++ doc/source/resumption.rst | 14 +++++++------- 7 files changed, 37 insertions(+), 17 deletions(-) diff --git a/doc/source/arguments_and_results.rst b/doc/source/arguments_and_results.rst index 12ad6eddd..d7b960950 100644 --- a/doc/source/arguments_and_results.rst +++ b/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. diff --git a/doc/source/atoms.rst b/doc/source/atoms.rst index 26ca6ad0f..f2b75ffa0 100644 --- a/doc/source/atoms.rst +++ b/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:: diff --git a/doc/source/engines.rst b/doc/source/engines.rst index 45113a378..be19aa454 100644 --- a/doc/source/engines.rst +++ b/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'`` diff --git a/doc/source/index.rst b/doc/source/index.rst index 23ffcfcb3..d3820470d 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -14,7 +14,7 @@ Contents ======== .. toctree:: - :maxdepth: 2 + :maxdepth: 3 atoms arguments_and_results diff --git a/doc/source/jobs.rst b/doc/source/jobs.rst index 048a66ea4..4c482b51e 100644 --- a/doc/source/jobs.rst +++ b/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/ diff --git a/doc/source/persistence.rst b/doc/source/persistence.rst index 022773e53..18fe6bff5 100644 --- a/doc/source/persistence.rst +++ b/doc/source/persistence.rst @@ -144,6 +144,9 @@ the following: ``'connection'`` and possibly type-specific backend parameters as other keys. +Types +===== + Memory ------ diff --git a/doc/source/resumption.rst b/doc/source/resumption.rst index 8ddd4e955..3be864f69 100644 --- a/doc/source/resumption.rst +++ b/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