From 1229eb2e8e990ad78d45ba5f64ee05d5ef521d78 Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Fri, 7 Jul 2017 19:48:10 -0400 Subject: [PATCH] rearrange existing documentation into the new standard layout Change-Id: Ic53baaa62771fda6de3b3dfe861909365103d1a9 Signed-off-by: Doug Hellmann --- doc/source/history.rst | 2 - doc/source/index.rst | 104 +----------------- .../{ => user}/arguments_and_results.rst | 0 doc/source/{ => user}/atoms.rst | 0 doc/source/{ => user}/conductors.rst | 0 doc/source/{ => user}/engines.rst | 0 doc/source/{ => user}/examples.rst | 81 +++++++++----- doc/source/{ => user}/exceptions.rst | 0 doc/source/user/history.rst | 2 + .../{ => user}/img/area_of_influence.svg | 0 doc/source/{ => user}/img/conductor.png | Bin doc/source/{ => user}/img/conductor_cycle.png | Bin .../{ => user}/img/distributed_flow_rpc.png | Bin doc/source/{ => user}/img/engine_states.svg | 0 doc/source/{ => user}/img/flow_states.svg | 0 doc/source/{ => user}/img/job_states.svg | 0 doc/source/{ => user}/img/jobboard.png | Bin doc/source/{ => user}/img/mandelbrot.png | Bin doc/source/{ => user}/img/retry_states.svg | 0 doc/source/{ => user}/img/task_states.svg | 0 doc/source/{ => user}/img/tasks.png | Bin .../{ => user}/img/wbe_request_states.svg | 0 doc/source/{ => user}/img/worker-engine.svg | 0 doc/source/user/index.rst | 80 ++++++++++++++ doc/source/{ => user}/inputs_and_outputs.rst | 0 doc/source/{ => user}/jobs.rst | 0 doc/source/{ => user}/notifications.rst | 0 doc/source/{ => user}/patterns.rst | 0 doc/source/{ => user}/persistence.rst | 0 doc/source/{ => user}/resumption.rst | 0 doc/source/{ => user}/shelf.rst | 0 doc/source/{ => user}/states.rst | 0 doc/source/{ => user}/types.rst | 0 doc/source/{ => user}/utils.rst | 0 doc/source/{ => user}/workers.rst | 0 35 files changed, 137 insertions(+), 132 deletions(-) delete mode 100644 doc/source/history.rst rename doc/source/{ => user}/arguments_and_results.rst (100%) rename doc/source/{ => user}/atoms.rst (100%) rename doc/source/{ => user}/conductors.rst (100%) rename doc/source/{ => user}/engines.rst (100%) rename doc/source/{ => user}/examples.rst (67%) rename doc/source/{ => user}/exceptions.rst (100%) create mode 100644 doc/source/user/history.rst rename doc/source/{ => user}/img/area_of_influence.svg (100%) rename doc/source/{ => user}/img/conductor.png (100%) rename doc/source/{ => user}/img/conductor_cycle.png (100%) rename doc/source/{ => user}/img/distributed_flow_rpc.png (100%) rename doc/source/{ => user}/img/engine_states.svg (100%) rename doc/source/{ => user}/img/flow_states.svg (100%) rename doc/source/{ => user}/img/job_states.svg (100%) rename doc/source/{ => user}/img/jobboard.png (100%) rename doc/source/{ => user}/img/mandelbrot.png (100%) rename doc/source/{ => user}/img/retry_states.svg (100%) rename doc/source/{ => user}/img/task_states.svg (100%) rename doc/source/{ => user}/img/tasks.png (100%) rename doc/source/{ => user}/img/wbe_request_states.svg (100%) rename doc/source/{ => user}/img/worker-engine.svg (100%) create mode 100644 doc/source/user/index.rst rename doc/source/{ => user}/inputs_and_outputs.rst (100%) rename doc/source/{ => user}/jobs.rst (100%) rename doc/source/{ => user}/notifications.rst (100%) rename doc/source/{ => user}/patterns.rst (100%) rename doc/source/{ => user}/persistence.rst (100%) rename doc/source/{ => user}/resumption.rst (100%) rename doc/source/{ => user}/shelf.rst (100%) rename doc/source/{ => user}/states.rst (100%) rename doc/source/{ => user}/types.rst (100%) rename doc/source/{ => user}/utils.rst (100%) rename doc/source/{ => user}/workers.rst (100%) diff --git a/doc/source/history.rst b/doc/source/history.rst deleted file mode 100644 index db8340b5..00000000 --- a/doc/source/history.rst +++ /dev/null @@ -1,2 +0,0 @@ -.. include:: ../../ChangeLog - diff --git a/doc/source/index.rst b/doc/source/index.rst index 2bbc0019..d292173c 100644 --- a/doc/source/index.rst +++ b/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 - 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 + user/index Indices and tables ================== diff --git a/doc/source/arguments_and_results.rst b/doc/source/user/arguments_and_results.rst similarity index 100% rename from doc/source/arguments_and_results.rst rename to doc/source/user/arguments_and_results.rst diff --git a/doc/source/atoms.rst b/doc/source/user/atoms.rst similarity index 100% rename from doc/source/atoms.rst rename to doc/source/user/atoms.rst diff --git a/doc/source/conductors.rst b/doc/source/user/conductors.rst similarity index 100% rename from doc/source/conductors.rst rename to doc/source/user/conductors.rst diff --git a/doc/source/engines.rst b/doc/source/user/engines.rst similarity index 100% rename from doc/source/engines.rst rename to doc/source/user/engines.rst diff --git a/doc/source/examples.rst b/doc/source/user/examples.rst similarity index 67% rename from doc/source/examples.rst rename to doc/source/user/examples.rst index 2edfb656..83452241 100644 --- a/doc/source/examples.rst +++ b/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- diff --git a/doc/source/exceptions.rst b/doc/source/user/exceptions.rst similarity index 100% rename from doc/source/exceptions.rst rename to doc/source/user/exceptions.rst diff --git a/doc/source/user/history.rst b/doc/source/user/history.rst new file mode 100644 index 00000000..2632296e --- /dev/null +++ b/doc/source/user/history.rst @@ -0,0 +1,2 @@ +.. include:: ../../../ChangeLog + diff --git a/doc/source/img/area_of_influence.svg b/doc/source/user/img/area_of_influence.svg similarity index 100% rename from doc/source/img/area_of_influence.svg rename to doc/source/user/img/area_of_influence.svg diff --git a/doc/source/img/conductor.png b/doc/source/user/img/conductor.png similarity index 100% rename from doc/source/img/conductor.png rename to doc/source/user/img/conductor.png diff --git a/doc/source/img/conductor_cycle.png b/doc/source/user/img/conductor_cycle.png similarity index 100% rename from doc/source/img/conductor_cycle.png rename to doc/source/user/img/conductor_cycle.png diff --git a/doc/source/img/distributed_flow_rpc.png b/doc/source/user/img/distributed_flow_rpc.png similarity index 100% rename from doc/source/img/distributed_flow_rpc.png rename to doc/source/user/img/distributed_flow_rpc.png diff --git a/doc/source/img/engine_states.svg b/doc/source/user/img/engine_states.svg similarity index 100% rename from doc/source/img/engine_states.svg rename to doc/source/user/img/engine_states.svg diff --git a/doc/source/img/flow_states.svg b/doc/source/user/img/flow_states.svg similarity index 100% rename from doc/source/img/flow_states.svg rename to doc/source/user/img/flow_states.svg diff --git a/doc/source/img/job_states.svg b/doc/source/user/img/job_states.svg similarity index 100% rename from doc/source/img/job_states.svg rename to doc/source/user/img/job_states.svg diff --git a/doc/source/img/jobboard.png b/doc/source/user/img/jobboard.png similarity index 100% rename from doc/source/img/jobboard.png rename to doc/source/user/img/jobboard.png diff --git a/doc/source/img/mandelbrot.png b/doc/source/user/img/mandelbrot.png similarity index 100% rename from doc/source/img/mandelbrot.png rename to doc/source/user/img/mandelbrot.png diff --git a/doc/source/img/retry_states.svg b/doc/source/user/img/retry_states.svg similarity index 100% rename from doc/source/img/retry_states.svg rename to doc/source/user/img/retry_states.svg diff --git a/doc/source/img/task_states.svg b/doc/source/user/img/task_states.svg similarity index 100% rename from doc/source/img/task_states.svg rename to doc/source/user/img/task_states.svg diff --git a/doc/source/img/tasks.png b/doc/source/user/img/tasks.png similarity index 100% rename from doc/source/img/tasks.png rename to doc/source/user/img/tasks.png diff --git a/doc/source/img/wbe_request_states.svg b/doc/source/user/img/wbe_request_states.svg similarity index 100% rename from doc/source/img/wbe_request_states.svg rename to doc/source/user/img/wbe_request_states.svg diff --git a/doc/source/img/worker-engine.svg b/doc/source/user/img/worker-engine.svg similarity index 100% rename from doc/source/img/worker-engine.svg rename to doc/source/user/img/worker-engine.svg diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst new file mode 100644 index 00000000..8bde08d1 --- /dev/null +++ b/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 diff --git a/doc/source/inputs_and_outputs.rst b/doc/source/user/inputs_and_outputs.rst similarity index 100% rename from doc/source/inputs_and_outputs.rst rename to doc/source/user/inputs_and_outputs.rst diff --git a/doc/source/jobs.rst b/doc/source/user/jobs.rst similarity index 100% rename from doc/source/jobs.rst rename to doc/source/user/jobs.rst diff --git a/doc/source/notifications.rst b/doc/source/user/notifications.rst similarity index 100% rename from doc/source/notifications.rst rename to doc/source/user/notifications.rst diff --git a/doc/source/patterns.rst b/doc/source/user/patterns.rst similarity index 100% rename from doc/source/patterns.rst rename to doc/source/user/patterns.rst diff --git a/doc/source/persistence.rst b/doc/source/user/persistence.rst similarity index 100% rename from doc/source/persistence.rst rename to doc/source/user/persistence.rst diff --git a/doc/source/resumption.rst b/doc/source/user/resumption.rst similarity index 100% rename from doc/source/resumption.rst rename to doc/source/user/resumption.rst diff --git a/doc/source/shelf.rst b/doc/source/user/shelf.rst similarity index 100% rename from doc/source/shelf.rst rename to doc/source/user/shelf.rst diff --git a/doc/source/states.rst b/doc/source/user/states.rst similarity index 100% rename from doc/source/states.rst rename to doc/source/user/states.rst diff --git a/doc/source/types.rst b/doc/source/user/types.rst similarity index 100% rename from doc/source/types.rst rename to doc/source/user/types.rst diff --git a/doc/source/utils.rst b/doc/source/user/utils.rst similarity index 100% rename from doc/source/utils.rst rename to doc/source/user/utils.rst diff --git a/doc/source/workers.rst b/doc/source/user/workers.rst similarity index 100% rename from doc/source/workers.rst rename to doc/source/user/workers.rst