Update documentation

Author: codingjoe

docs/core_components.rst

@@ -36,8 +36,8 @@ Edges are the glue that binds tasks together. They define the transitions
 between tasks. They are represented by a simple list of tuples. Edges have no
 behavior but define the structure of a workflow.
 
-Component API
--------------
+Advanced Process API
+--------------------
 
 .. autoclass:: galahad.models.Process
     :show-inheritance:

docs/tasks.rst

@@ -8,11 +8,117 @@ Tasks
 Human
 -----
 
+Human tasks are represented by a Django :class:`View<django.views.generic.base.View>`.
+
+A user can change the processes state via a Django form or a JSON API.
+Anything you can do in a view you can do in a human task. They only
+difference to machine tasks is that they require some kind of interaction.
+
+You can use view mixins like the
+:class:`PermissionRequiredMixin<django.contrib.auth.mixins.PermissionRequiredMixin>`
+or
+:class:`LoginRequiredMixin<django.contrib.auth.mixins.LoginRequiredMixin>`
+to create your own tasks that are only available to certain users.
+
+Generic human tasks
+~~~~~~~~~~~~~~~~~~~
+
 .. automodule:: galahad.tasks.human
     :members:
 
 Machine
 -------
 
+Machine tasks are represented by simple methods on the `Process` class.
+
+They can change the state and perform any action you can think of. They can
+decide which task to execute next (exclusive gateway) but also start or wait
+for multiple other tasks (split/join gateways).
+
+Furthermore tasks can implement things like sending emails or fetching data
+from an 3rd party API. All tasks are executed asynchronously to avoid blocking
+IO and locked to prevent raise conditions.
+
+Return values
+~~~~~~~~~~~~~
+
+Machine tasks have three different allowed return values all of which will
+cause the process to behave differently:
+
+``None``:
+    If a task returns ``None`` or anything at all the process will just
+    proceed as planed and follow all outgoing edges and execute the nexttasks.
+
+``Iterable``:
+    A task can return also an explicit list of tasks that should be executed
+    next. This can be used to create exclusive gateways::
+
+        from django.utils import timezone
+        from galahad.models import Process
+        from galahad import tasks
+
+
+        class ExclusiveProcess(Process):
+            start = tasks.Start()
+
+            def is_workday(self):
+                if timezone.localtime().weekday() < 5:
+                    return [self.work]
+                else:
+                    return [self.chill]
+
+            def work(self):
+                # pass time at the water cooler
+                pass
+
+            def chill(self):
+                # enjoy life
+                pass
+
+            edges = (
+                (start, is_workday),
+                (is_workday, work),
+                (is_workday, chill),
+            )
+
+    A task can also return am empty list. This will cause the process branch
+    to come to a halt and no further stats will be started.
+
+``False``:
+    A task can also return a boolean. Should a task return ``False`` the
+    process will wait until the condition changes to ``True`` (or anything but
+    ``False``)::
+
+        from galahad.models import Process
+        from galahad import tasks
+        from django.utils import timezone
+
+
+        class WaitingProcess(Process):
+            start = tasks.Start()
+
+            def wait_for_weekend(self):
+                return timezone.now().weekday() >= 5
+
+            def go_home(self):
+                # enjoy life
+                pass
+
+            edges = (
+                (start, wait_for_weekend),
+                (wait_for_weekend, go_home),
+            )
+
+Exceptions
+~~~~~~~~~~
+
+Should a task raise an exception the tasks will change it status to failed.
+The exception that caused the task to fail will be recorded on the task
+itself and further propagated. You can find and rerun failed tasks form
+Django's admin interface.
+
+Generic machine tasks
+~~~~~~~~~~~~~~~~~~~~~
+
 .. automodule:: galahad.tasks.machine
     :members:

galahad/tasks/__init__.py

@@ -3,18 +3,6 @@
 
 A task can be considered as a simple transaction that changes state of a process.
 There are two types of tasks, human and machine tasks.
-
-Human tasks are represented by a Django :class:`View<django.views.generic.base.View>`.
-A user can change the processes state via a Django form or a JSON API.
-
-Machine tasks are represented by simple methods on the `Process` class. They
-can change the state and perform any action you can think of. They can decide
-which task to execute next (exclusive gateway) but also start or wait for multiple
-other tasks (split/join gateways).
-
-Furthermore tasks can implement things like sending emails or fetching data
-from an 3rd party API. All tasks are executed asynchronously to avoid blocking
-IO and locked to prevent raise conditions.
 """
 from .machine import *  # NoQA
 from .human import *  # NoQA

galahad/tasks/human.py

@@ -1,3 +1,4 @@
+"""Set of reusable human tasks."""
 from django.views import generic
 
 from galahad.views import TaskViewMixin

galahad/tasks/machine.py

@@ -1,3 +1,4 @@
+"""Set of reusable machine tasks."""
 from typing import Iterable
 from django.utils import timezone