Match internal reference name with directory structure, updates to in…

…ternal reference documentation and docstrings

botoflow/decisions/decision_bases.py

@@ -10,15 +10,33 @@
 # on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
 # express or implied. See the License for the specific language governing
 # permissions and limitations under the License.
+"""
+Decision bases are base classes for various decision classes, essentially grouping and reusing common bits between
+actual decisions.
+
+"""
+
 
 class DecisionBase(object):
+    """Every decision or decision base should inherit from this class
+
+    .. py:data:: decision
+
+        Contains a dictionary of decision attributes
+    """
+
     def __init__(self):
-        self.decision = dict()
+        self.decision = {}
 
 
 class ActivityDecisionBase(DecisionBase):
+    """Base for Activity decisions
+    """
 
     def __init__(self, decision_id):
+        """
+        :param str decision_id: Decision ID
+        """
         super(ActivityDecisionBase, self).__init__()
         self.decision_id = decision_id
 
@@ -28,7 +46,14 @@ def __repr__(self):
 
 
 class RequestCancelExternalWorkflowDecisionBase(DecisionBase):
+    """Base for requesting a cancellation of external workflow
+    """
+
     def __init__(self, workflow_id, run_id):
+        """
+        :param str workflow_id: Workflow ID
+        :param str run_id: Run ID
+        """
         super(RequestCancelExternalWorkflowDecisionBase, self).__init__()
         self.decision_id = (workflow_id, run_id)
 
@@ -39,7 +64,12 @@ def __repr__(self):
 
 
 class RecordMarkerDecisionBase(DecisionBase):
+    """Record marker decision base"""
+
     def __init__(self, decision_id):
+        """
+        :param str decision_id: Decision ID
+        """
         super(RecordMarkerDecisionBase, self).__init__()
         self.decision_id = decision_id
 
@@ -49,7 +79,15 @@ def __repr__(self):
 
 
 class SignalExternalWorkflowExecutionDecisionBase(DecisionBase):
+    """Signalling for external workflow
+    """
+
     def __init__(self, workflow_id, run_id, signal_name):
+        """
+        :param str workflow_id: Workflow ID
+        :param str run_id: Run ID
+        :param str signal_name: name of the signal to execute
+        """
         super(SignalExternalWorkflowExecutionDecisionBase, self).__init__()
         self.decision_id = (workflow_id, run_id, signal_name)
 
@@ -61,7 +99,15 @@ def __repr__(self):
 
 
 class StartChildWorkflowExecutionDecisionBase(DecisionBase):
+    """Starting child workflow base
+    """
+
     def __init__(self, workflow_type_name, workflow_type_version, workflow_id):
+        """
+        :param str workflow_type_name: Workflow type name
+        :param str workflow_type_version: version of the workflow
+        :param str workflow_id: Workflow ID
+        """
         super(StartChildWorkflowExecutionDecisionBase, self).__init__()
         self.decision_id = (workflow_type_name, workflow_type_version,
                             workflow_id)
@@ -74,8 +120,13 @@ def __repr__(self):
 
 
 class TimerDecisionBase(DecisionBase):
+    """Timer decisions base
+    """
 
     def __init__(self, decision_id):
+        """
+        :param str decision_id: Decision ID
+        """
         super(TimerDecisionBase, self).__init__()
         self.decision_id = decision_id
 
@@ -85,6 +136,7 @@ def __repr__(self):
 
 
 class WorkflowDecisionBase(DecisionBase):
+    """Workflow decision base"""
 
     def __init__(self):
         super(WorkflowDecisionBase, self).__init__()

botoflow/decorator_descriptors.py

@@ -11,8 +11,15 @@
 # express or implied. See the License for the specific language governing
 # permissions and limitations under the License.
 
-"""Internal: for use by decorators
+"""Descriptors allow us to manipulate Python functions/methods at a much deeper level.
+
+This is extremely useful for our workflow and activity decorators as descriptors allow us to perform different
+actions depending on whether the call was made from the class or instance. Thereby allowing things like calling
+activities from the workflow execution as if they were classmethod*s*.
+
+To learn more about descriptors and using them, please check the official Python documentation: :ref:`descriptors`.
 """
+
 import functools
 from .context import get_context, StartWorkflowContext, DecisionContext
 from .core import async

docs/source/index.rst

@@ -89,7 +89,7 @@ Internal Reference
 .. toctree::
    :maxdepth: 3
 
-   developer_reference/index
+   internal_reference/index
 
 ==================
 Indices and tables

docs/source/internal_reference/activity_retrying.rst

@@ -0,0 +1,6 @@
+Activity Retrying
+=================
+
+.. automodule:: botoflow.activity_retrying
+   :members:
+   :undoc-members:

docs/source/internal_reference/decisions.rst

@@ -0,0 +1,28 @@
+=========
+Decisions
+=========
+
+``decisions`` are classes/encapsulations of decisions we send to SWF.
+
+Decision Bases
+--------------
+
+.. automodule:: botoflow.decisions.decision_bases
+   :members:
+   :undoc-members:
+
+Decision List
+-------------
+
+.. automodule:: botoflow.decisions.decision_list
+   :members:
+   :undoc-members:
+
+Decisions
+---------
+
+.. automodule:: botoflow.decisions.decisions
+   :members:
+   :undoc-members:
+
+

docs/source/developer_reference/decorator_descriptors.rst → docs/source/internal_reference/decorator_descriptors.rst

@@ -1,5 +1,4 @@
-=====================
-decorator_descriptors
+Decorator Descriptors
 =====================
 
 botoflow.decorator_descriptors

docs/source/developer_reference/index.rst → docs/source/internal_reference/index.rst

@@ -1,11 +1,14 @@
 Internal Reference
 ==================
 
-Internal reference documentation for botoflow developers.
+.. note::
+
+   Internal reference documentation for botoflow developers.
 
 .. toctree::
    :maxdepth: 4
 
+   activity_retrying
    core
    decider
    decisions