rearrange existing documentation into the new standard layout

Change-Id: Ic53baaa62771fda6de3b3dfe861909365103d1a9
Signed-off-by: Doug Hellmann <doug@doughellmann.com>

doc/source/history.rst

@@ -1,2 +0,0 @@
-.. include:: ../../ChangeLog
-

doc/source/index.rst

@@ -1,5 +1,6 @@
-TaskFlow
+==========
-========
+ TaskFlow
+==========
 
 *TaskFlow is a Python library that helps to make task execution easy,
 consistent and reliable.* [#f1]_
@@ -10,107 +11,10 @@ consistent and reliable.* [#f1]_
     visit: http://wiki.openstack.org/wiki/TaskFlow which provides better
     introductory material, description of high level goals and related content.
 
-Contents
-========
-
 .. toctree::
    :maxdepth: 2
 
-   atoms
+   user/index
-   arguments_and_results
-   inputs_and_outputs
-
-   patterns
-   engines
-   notifications
-   persistence
-   resumption
-
-   jobs
-   conductors
-
-Supplementary
-=============
-
-Examples
---------
-
-While developing TaskFlow the team has worked *hard* to make sure the various
-concepts are explained by *relevant* examples. Here are a few selected examples
-to get started (ordered by *perceived* complexity):
-
-.. toctree::
-   :maxdepth: 2
-
-   examples
-
-To explore more of these examples please check out the `examples`_ directory
-in the TaskFlow `source tree`_.
-
-.. note::
-
-    If the examples provided are not satisfactory (or up to your
-    standards) contributions are welcome and very much appreciated to help
-    improve them. The higher the quality and the clearer the examples are the
-    better and more useful they are for everyone.
-
-.. _examples: http://git.openstack.org/cgit/openstack/taskflow/tree/taskflow/examples
-.. _source tree: http://git.openstack.org/cgit/openstack/taskflow/
-
-Considerations
---------------
-
-Things to consider before (and during) development and integration with
-TaskFlow into your project:
-
-* Read over the `paradigm shifts`_ and engage the team in `IRC`_ (or via the
-  `openstack-dev`_ mailing list) if these need more explanation (prefix
-  ``[Oslo][TaskFlow]`` to your emails subject to get an even faster
-  response).
-* Follow (or at least attempt to follow) some of the established
-  `best practices`_ (feel free to add your own suggested best practices).
-* Keep in touch with the team (see above); we are all friendly and enjoy
-  knowing your use cases and learning how we can help make your lives easier
-  by adding or adjusting functionality in this library.
-
-.. _IRC: irc://chat.freenode.net/openstack-state-management
-.. _best practices: http://wiki.openstack.org/wiki/TaskFlow/Best_practices
-.. _paradigm shifts: http://wiki.openstack.org/wiki/TaskFlow/Paradigm_shifts
-.. _openstack-dev: mailto:openstack-dev@lists.openstack.org
-
-Miscellaneous
--------------
-
-.. toctree::
-   :maxdepth: 2
-
-   exceptions
-   states
-   types
-   utils
-
-Bookshelf
----------
-
-A useful collection of links, documents, papers, similar
-projects, frameworks and libraries.
-
-.. note::
-
-     Please feel free to submit your own additions and/or changes.
-
-.. toctree::
-   :maxdepth: 1
-
-   shelf
-
-Release notes
--------------
-
-.. toctree::
-   :maxdepth: 2
-
-   history
 
 Indices and tables
 ==================

doc/source/user/examples.rst

@@ -1,3 +1,24 @@
+==========
+ Examples
+==========
+
+While developing TaskFlow the team has worked *hard* to make sure the various
+concepts are explained by *relevant* examples. Here are a few selected examples
+to get started (ordered by *perceived* complexity):
+
+To explore more of these examples please check out the `examples`_ directory
+in the TaskFlow `source tree`_.
+
+.. note::
+
+    If the examples provided are not satisfactory (or up to your
+    standards) contributions are welcome and very much appreciated to help
+    improve them. The higher the quality and the clearer the examples are the
+    better and more useful they are for everyone.
+
+.. _examples: http://git.openstack.org/cgit/openstack/taskflow/tree/taskflow/examples
+.. _source tree: http://git.openstack.org/cgit/openstack/taskflow/
+
 Hello world
 ===========
 
@@ -5,7 +26,7 @@ Hello world
 
     Full source located at :example:`hello_world`.
 
-.. literalinclude:: ../../taskflow/examples/hello_world.py
+.. literalinclude:: ../../../taskflow/examples/hello_world.py
     :language: python
     :linenos:
     :lines: 16-
@@ -17,7 +38,7 @@ Passing values from and to tasks
 
     Full source located at :example:`simple_linear_pass`.
 
-.. literalinclude:: ../../taskflow/examples/simple_linear_pass.py
+.. literalinclude:: ../../../taskflow/examples/simple_linear_pass.py
     :language: python
     :linenos:
     :lines: 16-
@@ -29,7 +50,7 @@ Using listeners
 
     Full source located at :example:`echo_listener`.
 
-.. literalinclude:: ../../taskflow/examples/echo_listener.py
+.. literalinclude:: ../../../taskflow/examples/echo_listener.py
     :language: python
     :linenos:
     :lines: 16-
@@ -41,7 +62,7 @@ Using listeners (to watch a phone call)
 
     Full source located at :example:`simple_linear_listening`.
 
-.. literalinclude:: ../../taskflow/examples/simple_linear_listening.py
+.. literalinclude:: ../../../taskflow/examples/simple_linear_listening.py
     :language: python
     :linenos:
     :lines: 16-
@@ -53,7 +74,7 @@ Dumping a in-memory backend
 
     Full source located at :example:`dump_memory_backend`.
 
-.. literalinclude:: ../../taskflow/examples/dump_memory_backend.py
+.. literalinclude:: ../../../taskflow/examples/dump_memory_backend.py
     :language: python
     :linenos:
     :lines: 16-
@@ -65,7 +86,7 @@ Making phone calls
 
     Full source located at :example:`simple_linear`.
 
-.. literalinclude:: ../../taskflow/examples/simple_linear.py
+.. literalinclude:: ../../../taskflow/examples/simple_linear.py
     :language: python
     :linenos:
     :lines: 16-
@@ -77,7 +98,7 @@ Making phone calls (automatically reverting)
 
     Full source located at :example:`reverting_linear`.
 
-.. literalinclude:: ../../taskflow/examples/reverting_linear.py
+.. literalinclude:: ../../../taskflow/examples/reverting_linear.py
     :language: python
     :linenos:
     :lines: 16-
@@ -89,7 +110,7 @@ Building a car
 
     Full source located at :example:`build_a_car`.
 
-.. literalinclude:: ../../taskflow/examples/build_a_car.py
+.. literalinclude:: ../../../taskflow/examples/build_a_car.py
     :language: python
     :linenos:
     :lines: 16-
@@ -101,7 +122,7 @@ Iterating over the alphabet (using processes)
 
     Full source located at :example:`alphabet_soup`.
 
-.. literalinclude:: ../../taskflow/examples/alphabet_soup.py
+.. literalinclude:: ../../../taskflow/examples/alphabet_soup.py
     :language: python
     :linenos:
     :lines: 16-
@@ -113,7 +134,7 @@ Watching execution timing
 
     Full source located at :example:`timing_listener`.
 
-.. literalinclude:: ../../taskflow/examples/timing_listener.py
+.. literalinclude:: ../../../taskflow/examples/timing_listener.py
     :language: python
     :linenos:
     :lines: 16-
@@ -125,7 +146,7 @@ Distance calculator
 
     Full source located at :example:`distance_calculator`
 
-.. literalinclude:: ../../taskflow/examples/distance_calculator.py
+.. literalinclude:: ../../../taskflow/examples/distance_calculator.py
     :language: python
     :linenos:
     :lines: 16-
@@ -137,7 +158,7 @@ Table multiplier (in parallel)
 
     Full source located at :example:`parallel_table_multiply`
 
-.. literalinclude:: ../../taskflow/examples/parallel_table_multiply.py
+.. literalinclude:: ../../../taskflow/examples/parallel_table_multiply.py
     :language: python
     :linenos:
     :lines: 16-
@@ -149,7 +170,7 @@ Linear equation solver (explicit dependencies)
 
     Full source located at :example:`calculate_linear`.
 
-.. literalinclude:: ../../taskflow/examples/calculate_linear.py
+.. literalinclude:: ../../../taskflow/examples/calculate_linear.py
     :language: python
     :linenos:
     :lines: 16-
@@ -159,7 +180,7 @@ Linear equation solver (inferred dependencies)
 
 ``Source:`` :example:`graph_flow.py`
 
-.. literalinclude:: ../../taskflow/examples/graph_flow.py
+.. literalinclude:: ../../../taskflow/examples/graph_flow.py
     :language: python
     :linenos:
     :lines: 16-
@@ -171,7 +192,7 @@ Linear equation solver (in parallel)
 
     Full source located at :example:`calculate_in_parallel`
 
-.. literalinclude:: ../../taskflow/examples/calculate_in_parallel.py
+.. literalinclude:: ../../../taskflow/examples/calculate_in_parallel.py
     :language: python
     :linenos:
     :lines: 16-
@@ -183,7 +204,7 @@ Creating a volume (in parallel)
 
     Full source located at :example:`create_parallel_volume`
 
-.. literalinclude:: ../../taskflow/examples/create_parallel_volume.py
+.. literalinclude:: ../../../taskflow/examples/create_parallel_volume.py
     :language: python
     :linenos:
     :lines: 16-
@@ -195,7 +216,7 @@ Summation mapper(s) and reducer (in parallel)
 
     Full source located at :example:`simple_map_reduce`
 
-.. literalinclude:: ../../taskflow/examples/simple_map_reduce.py
+.. literalinclude:: ../../../taskflow/examples/simple_map_reduce.py
     :language: python
     :linenos:
     :lines: 16-
@@ -207,7 +228,7 @@ Sharing a thread pool executor (in parallel)
 
     Full source located at :example:`share_engine_thread`
 
-.. literalinclude:: ../../taskflow/examples/share_engine_thread.py
+.. literalinclude:: ../../../taskflow/examples/share_engine_thread.py
     :language: python
     :linenos:
     :lines: 16-
@@ -219,7 +240,7 @@ Storing & emitting a bill
 
     Full source located at :example:`fake_billing`
 
-.. literalinclude:: ../../taskflow/examples/fake_billing.py
+.. literalinclude:: ../../../taskflow/examples/fake_billing.py
     :language: python
     :linenos:
     :lines: 16-
@@ -231,7 +252,7 @@ Suspending a workflow & resuming
 
     Full source located at :example:`resume_from_backend`
 
-.. literalinclude:: ../../taskflow/examples/resume_from_backend.py
+.. literalinclude:: ../../../taskflow/examples/resume_from_backend.py
     :language: python
     :linenos:
     :lines: 16-
@@ -243,7 +264,7 @@ Creating a virtual machine (resumable)
 
     Full source located at :example:`resume_vm_boot`
 
-.. literalinclude:: ../../taskflow/examples/resume_vm_boot.py
+.. literalinclude:: ../../../taskflow/examples/resume_vm_boot.py
     :language: python
     :linenos:
     :lines: 16-
@@ -255,7 +276,7 @@ Creating a volume (resumable)
 
     Full source located at :example:`resume_volume_create`
 
-.. literalinclude:: ../../taskflow/examples/resume_volume_create.py
+.. literalinclude:: ../../../taskflow/examples/resume_volume_create.py
     :language: python
     :linenos:
     :lines: 16-
@@ -267,7 +288,7 @@ Running engines via iteration
 
     Full source located at :example:`run_by_iter`
 
-.. literalinclude:: ../../taskflow/examples/run_by_iter.py
+.. literalinclude:: ../../../taskflow/examples/run_by_iter.py
     :language: python
     :linenos:
     :lines: 16-
@@ -279,7 +300,7 @@ Controlling retries using a retry controller
 
     Full source located at :example:`retry_flow`
 
-.. literalinclude:: ../../taskflow/examples/retry_flow.py
+.. literalinclude:: ../../../taskflow/examples/retry_flow.py
     :language: python
     :linenos:
     :lines: 16-
@@ -291,7 +312,7 @@ Distributed execution (simple)
 
     Full source located at :example:`wbe_simple_linear`
 
-.. literalinclude:: ../../taskflow/examples/wbe_simple_linear.py
+.. literalinclude:: ../../../taskflow/examples/wbe_simple_linear.py
     :language: python
     :linenos:
     :lines: 16-
@@ -303,7 +324,7 @@ Distributed notification (simple)
 
     Full source located at :example:`wbe_event_sender`
 
-.. literalinclude:: ../../taskflow/examples/wbe_event_sender.py
+.. literalinclude:: ../../../taskflow/examples/wbe_event_sender.py
     :language: python
     :linenos:
     :lines: 16-
@@ -326,7 +347,7 @@ Output
 Code
 ----
 
-.. literalinclude:: ../../taskflow/examples/wbe_mandelbrot.py
+.. literalinclude:: ../../../taskflow/examples/wbe_mandelbrot.py
     :language: python
     :linenos:
     :lines: 16-
@@ -338,7 +359,7 @@ Jobboard producer/consumer (simple)
 
     Full source located at :example:`jobboard_produce_consume_colors`
 
-.. literalinclude:: ../../taskflow/examples/jobboard_produce_consume_colors.py
+.. literalinclude:: ../../../taskflow/examples/jobboard_produce_consume_colors.py
     :language: python
     :linenos:
     :lines: 16-
@@ -350,7 +371,7 @@ Conductor simulating a CI pipeline
 
     Full source located at :example:`tox_conductor`
 
-.. literalinclude:: ../../taskflow/examples/tox_conductor.py
+.. literalinclude:: ../../../taskflow/examples/tox_conductor.py
     :language: python
     :linenos:
     :lines: 16-
@@ -363,7 +384,7 @@ Conductor running 99 bottles of beer song requests
 
     Full source located at :example:`99_bottles`
 
-.. literalinclude:: ../../taskflow/examples/99_bottles.py
+.. literalinclude:: ../../../taskflow/examples/99_bottles.py
     :language: python
     :linenos:
     :lines: 16-

doc/source/user/history.rst

@@ -0,0 +1,2 @@
+.. include:: ../../../ChangeLog
+

doc/source/user/index.rst

@@ -0,0 +1,80 @@
+================
+ Using TaskFlow
+================
+
+Considerations
+==============
+
+Things to consider before (and during) development and integration with
+TaskFlow into your project:
+
+* Read over the `paradigm shifts`_ and engage the team in `IRC`_ (or via the
+  `openstack-dev`_ mailing list) if these need more explanation (prefix
+  ``[Oslo][TaskFlow]`` to your emails subject to get an even faster
+  response).
+* Follow (or at least attempt to follow) some of the established
+  `best practices`_ (feel free to add your own suggested best practices).
+* Keep in touch with the team (see above); we are all friendly and enjoy
+  knowing your use cases and learning how we can help make your lives easier
+  by adding or adjusting functionality in this library.
+
+.. _IRC: irc://chat.freenode.net/openstack-state-management
+.. _best practices: http://wiki.openstack.org/wiki/TaskFlow/Best_practices
+.. _paradigm shifts: http://wiki.openstack.org/wiki/TaskFlow/Paradigm_shifts
+.. _openstack-dev: mailto:openstack-dev@lists.openstack.org
+
+User Guide
+==========
+
+.. toctree::
+   :maxdepth: 2
+
+   atoms
+   arguments_and_results
+   inputs_and_outputs
+
+   patterns
+   engines
+   workers
+   notifications
+   persistence
+   resumption
+
+   jobs
+   conductors
+
+   examples
+
+Miscellaneous
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   exceptions
+   states
+   types
+   utils
+
+Bookshelf
+=========
+
+A useful collection of links, documents, papers, similar
+projects, frameworks and libraries.
+
+.. note::
+
+     Please feel free to submit your own additions and/or changes.
+
+.. toctree::
+   :maxdepth: 1
+
+   shelf
+
+Release notes
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   history