ariatosca-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From emblempar...@apache.org
Subject [4/4] incubator-ariatosca git commit: Final work
Date Wed, 28 Jun 2017 23:29:26 GMT
Final work


Project: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/commit/5be27b0c
Tree: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/tree/5be27b0c
Diff: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/diff/5be27b0c

Branch: refs/heads/ARIA-286-sphinx-documentation
Commit: 5be27b0c0053dafacf67a4b0f068055c10dff28b
Parents: 4ebbbb1
Author: Tal Liron <tal.liron@gmail.com>
Authored: Wed Jun 28 18:27:11 2017 -0500
Committer: Tal Liron <tal.liron@gmail.com>
Committed: Wed Jun 28 18:27:11 2017 -0500

----------------------------------------------------------------------
 aria/logger.py                                  |   7 +-
 aria/modeling/mixins.py                         |  20 +--
 aria/modeling/models.py                         | 162 ++++++++++++-------
 aria/modeling/orchestration.py                  |  19 +--
 aria/modeling/relationship.py                   |  88 +++++-----
 aria/modeling/service_changes.py                |  13 +-
 aria/modeling/service_instance.py               |  16 +-
 aria/modeling/service_template.py               |   7 +-
 aria/modeling/utils.py                          |  29 +++-
 aria/orchestrator/__init__.py                   |   2 +-
 aria/orchestrator/context/__init__.py           |   2 +-
 aria/orchestrator/context/common.py             |  37 ++---
 aria/orchestrator/context/exceptions.py         |   4 +-
 aria/orchestrator/context/operation.py          |   8 +-
 aria/orchestrator/context/toolbelt.py           |  11 +-
 aria/orchestrator/context/workflow.py           |  22 ++-
 aria/orchestrator/decorators.py                 |   2 +-
 aria/orchestrator/events.py                     |   5 +-
 aria/orchestrator/exceptions.py                 |   4 +-
 aria/orchestrator/execution_plugin/__init__.py  |   4 +
 aria/orchestrator/execution_plugin/common.py    |  28 ++--
 aria/orchestrator/execution_plugin/constants.py |   4 +
 .../execution_plugin/ctx_proxy/__init__.py      |   4 +
 .../execution_plugin/ctx_proxy/client.py        |   4 +
 .../execution_plugin/ctx_proxy/server.py        |   4 +
 .../execution_plugin/environment_globals.py     |  63 ++++----
 .../orchestrator/execution_plugin/exceptions.py |  15 +-
 .../execution_plugin/instantiation.py           |   4 +
 aria/orchestrator/execution_plugin/local.py     |   4 +
 .../orchestrator/execution_plugin/operations.py |   4 +
 .../execution_plugin/ssh/__init__.py            |   4 +
 .../execution_plugin/ssh/operations.py          |   4 +
 aria/orchestrator/plugin.py                     |  22 ++-
 aria/orchestrator/workflow_runner.py            |  21 +--
 aria/orchestrator/workflows/__init__.py         |   4 +
 aria/orchestrator/workflows/api/__init__.py     |   2 +-
 aria/orchestrator/workflows/api/task.py         |  70 ++++----
 aria/orchestrator/workflows/api/task_graph.py   | 129 ++++++++-------
 aria/orchestrator/workflows/builtin/__init__.py |   2 +-
 .../workflows/builtin/execute_operation.py      |  14 +-
 aria/orchestrator/workflows/builtin/heal.py     |  36 ++---
 aria/orchestrator/workflows/builtin/install.py  |   5 +-
 aria/orchestrator/workflows/builtin/start.py    |   5 +-
 aria/orchestrator/workflows/builtin/stop.py     |   5 +-
 .../orchestrator/workflows/builtin/uninstall.py |   5 +-
 aria/orchestrator/workflows/core/__init__.py    |   2 +-
 aria/orchestrator/workflows/core/compile.py     |   8 +-
 aria/orchestrator/workflows/core/engine.py      |  10 +-
 .../workflows/core/events_handler.py            |   5 +-
 aria/orchestrator/workflows/events_logging.py   |   5 +-
 aria/orchestrator/workflows/exceptions.py       |  11 +-
 .../orchestrator/workflows/executor/__init__.py |   2 +-
 aria/orchestrator/workflows/executor/base.py    |   9 +-
 aria/orchestrator/workflows/executor/celery.py  |   4 +-
 aria/orchestrator/workflows/executor/dry.py     |   5 +-
 aria/orchestrator/workflows/executor/process.py |   4 +-
 aria/orchestrator/workflows/executor/thread.py  |  10 +-
 aria/parser/__init__.py                         |   2 +-
 aria/parser/consumption/__init__.py             |  32 ++++
 aria/parser/consumption/consumer.py             |   4 +-
 aria/parser/consumption/context.py              |   2 +
 aria/parser/consumption/presentation.py         |   5 +-
 aria/parser/exceptions.py                       |   4 +
 aria/parser/loading/__init__.py                 |  35 ++++
 aria/parser/loading/context.py                  |   4 +-
 aria/parser/loading/literal.py                  |   2 +-
 aria/parser/loading/location.py                 |   8 +-
 aria/parser/loading/source.py                   |   2 +-
 aria/parser/loading/uri.py                      |   4 +-
 aria/parser/modeling/__init__.py                |   4 +
 aria/parser/modeling/context.py                 |   4 +-
 aria/parser/presentation/__init__.py            |  84 +++++++++-
 aria/parser/presentation/context.py             |   8 +-
 aria/parser/presentation/presentation.py        |   2 +-
 aria/parser/reading/__init__.py                 |  23 +++
 aria/parser/reading/context.py                  |   2 +
 aria/parser/specification.py                    |   4 +
 aria/parser/validation/__init__.py              |   4 +
 aria/parser/validation/context.py               |   6 +-
 aria/storage/__init__.py                        |  23 +--
 aria/storage/api.py                             |  78 ++++-----
 aria/storage/collection_instrumentation.py      |  50 +++---
 aria/storage/core.py                            |  57 ++-----
 aria/storage/exceptions.py                      |   4 +-
 aria/storage/filesystem_rapi.py                 |  53 +++---
 aria/storage/sql_mapi.py                        |  71 ++++----
 aria/utils/archive.py                           |   2 +-
 aria/utils/argparse.py                          |   2 +-
 aria/utils/caching.py                           |   2 +-
 aria/utils/collections.py                       |  17 +-
 aria/utils/console.py                           |   2 +-
 aria/utils/exceptions.py                        |   2 +-
 aria/utils/file.py                              |   7 +-
 aria/utils/formatting.py                        |   4 +-
 aria/utils/http.py                              |  18 +--
 aria/utils/imports.py                           |  14 +-
 aria/utils/openclose.py                         |   4 +-
 aria/utils/plugin.py                            |   2 +-
 aria/utils/process.py                           |   2 +-
 aria/utils/specification.py                     |   2 +-
 aria/utils/threading.py                         |  45 +++---
 aria/utils/type.py                              |  14 +-
 aria/utils/uris.py                              |   4 +-
 aria/utils/uuid.py                              |  17 +-
 aria/utils/validation.py                        |   8 +-
 aria/utils/versions.py                          |  15 +-
 docs/aria.cli.rst                               |  34 ++--
 docs/aria.modeling.models.rst                   |   3 +-
 docs/aria.modeling.rst                          |  16 +-
 docs/aria.orchestrator.context.rst              |  46 ++++++
 ....orchestrator.execution_plugin.ctx_proxy.rst |  31 ++++
 docs/aria.orchestrator.execution_plugin.rst     |  39 ++++-
 docs/aria.orchestrator.execution_plugin.ssh.rst |  31 ++++
 docs/aria.orchestrator.rst                      |  28 +++-
 docs/aria.orchestrator.workflows.api.rst        |  31 ++++
 docs/aria.orchestrator.workflows.builtin.rst    |  57 +++++++
 docs/aria.orchestrator.workflows.executor.rst   |  46 ++++++
 docs/aria.orchestrator.workflows.rst            |  32 ++--
 docs/aria.parser.consumption.rst                |  42 +----
 docs/aria.parser.loading.rst                    |  47 +-----
 docs/aria.parser.modeling.rst                   |   7 +-
 docs/aria.parser.presentation.rst               |  47 +-----
 docs/aria.parser.reading.rst                    |  47 +-----
 docs/aria.parser.rst                            |   6 +-
 docs/aria.parser.validation.rst                 |  12 +-
 docs/aria.rst                                   |  10 +-
 docs/aria.storage.rst                           |  14 +-
 docs/aria.utils.rst                             |  42 ++---
 docs/aria_extension_tosca.rst                   |  30 ----
 docs/aria_extension_tosca.simple_nfv_v1_0.rst   |  20 +++
 ...ria_extension_tosca.simple_v1_0.modeling.rst |  75 +++++++++
 ...extension_tosca.simple_v1_0.presentation.rst |  40 +++++
 docs/aria_extension_tosca.simple_v1_0.rst       |  20 +++
 docs/conf.py                                    |  32 ++--
 docs/index.rst                                  |  12 +-
 docs/rest.rst                                   |  20 +++
 .../simple_nfv_v1_0/presenter.py                |   4 +-
 .../simple_v1_0/__init__.py                     | 109 +++++++++++++
 .../simple_v1_0/assignments.py                  |  44 ++---
 .../simple_v1_0/definitions.py                  |  79 ++++-----
 .../aria_extension_tosca/simple_v1_0/filters.py |   8 +-
 .../aria_extension_tosca/simple_v1_0/misc.py    |  56 +++++--
 .../simple_v1_0/modeling/capabilities.py        |   4 +-
 .../simple_v1_0/modeling/copy.py                |   2 +-
 .../simple_v1_0/modeling/data_types.py          |  10 +-
 .../simple_v1_0/modeling/functions.py           |  18 +--
 .../simple_v1_0/presentation/extensible.py      |   2 +-
 .../presentation/field_validators.py            |  40 ++---
 .../simple_v1_0/presentation/types.py           |  12 +-
 .../simple_v1_0/presenter.py                    |   4 +-
 .../simple_v1_0/templates.py                    |  96 +++++------
 .../aria_extension_tosca/simple_v1_0/types.py   |  98 +++++------
 152 files changed, 1971 insertions(+), 1295 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/logger.py
----------------------------------------------------------------------
diff --git a/aria/logger.py b/aria/logger.py
index 3b01e48..f4f6ec9 100644
--- a/aria/logger.py
+++ b/aria/logger.py
@@ -42,7 +42,7 @@ class LoggerMixin(object):
     Provides logging functionality to a class.
 
     :ivar logger_name: logger name; default to the class name
-    :ivar logger_level: logger level; defaults to `logging.DEBUG`
+    :ivar logger_level: logger level; defaults to ``logging.DEBUG``
     :ivar base_logger: child loggers are created from this; defaults to the root logger
     """
     logger_name = None
@@ -107,7 +107,6 @@ def create_console_log_handler(level=logging.DEBUG, formatter=None):
     """
     :param level:
     :param formatter:
-    :return:
     """
     console = logging.StreamHandler()
     console.setLevel(level)
@@ -124,9 +123,9 @@ def create_sqla_log_handler(model, log_cls, execution_id, level=logging.DEBUG):
 
 class _DefaultConsoleFormat(logging.Formatter):
     """
-    Info level log format: ``%(message)s``
+    Info level log format: ``%(message)s``.
 
-    Every other log level is formatted: ``%(levelname)s: %(message)s``
+    Every other log level is formatted: ``%(levelname)s: %(message)s``.
     """
     def format(self, record):
         try:

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/modeling/mixins.py
----------------------------------------------------------------------
diff --git a/aria/modeling/mixins.py b/aria/modeling/mixins.py
index aafc1e9..883ff4a 100644
--- a/aria/modeling/mixins.py
+++ b/aria/modeling/mixins.py
@@ -50,8 +50,8 @@ class ModelMixin(object):
         Create a dict representation of the model.
 
         :param suppress_error: if set to ``True``, sets ``None`` to attributes that it's unable to
-                               retrieve (e.g., if a relationship wasn't established yet, and so it's
-                               impossible to access a property through it)
+         retrieve (e.g., if a relationship wasn't established yet, and so it's impossible to access
+         a property through it)
         """
 
         res = dict()
@@ -125,7 +125,7 @@ class InstanceModelMixin(ModelMixin):
     Mix-in for service instance models.
 
     All models support validation, diagnostic dumping, and representation as raw data (which can be
-    translated into JSON or YAML) via ``as_raw``.
+    translated into JSON or YAML) via :meth:`as_raw`.
     """
 
     @property
@@ -198,7 +198,7 @@ class ParameterMixin(TemplateModelMixin, caching.HasCachedMethods):
 
         *All* parameters should have an owner model.
 
-        :raises exceptions.ValueError: if failed to find an owner, which signifies an abnormal,
+        :raises ~exceptions.ValueError: if failed to find an owner, which signifies an abnormal,
          orphaned parameter
         """
 
@@ -223,7 +223,7 @@ class ParameterMixin(TemplateModelMixin, caching.HasCachedMethods):
 
         *All* parameters should have a container model.
 
-        :raises exceptions.ValueError: if failed to find a container model, which signifies an
+        :raises ~exceptions.ValueError: if failed to find a container model, which signifies an
          abnormal, orphaned parameter
         """
 
@@ -269,7 +269,7 @@ class ParameterMixin(TemplateModelMixin, caching.HasCachedMethods):
         The :class:`~aria.modeling.models.Service` model containing this parameter, or ``None`` if
         not contained in a service.
 
-        :raises exceptions.ValueError: if failed to find a container model, which signifies an
+        :raises ~exceptions.ValueError: if failed to find a container model, which signifies an
          abnormal, orphaned parameter
         """
 
@@ -288,7 +288,7 @@ class ParameterMixin(TemplateModelMixin, caching.HasCachedMethods):
         The :class:`~aria.modeling.models.ServiceTemplate` model containing this parameter, or
         ``None`` if not contained in a service template.
 
-        :raises exceptions.ValueError: if failed to find a container model, which signifies an
+        :raises ~exceptions.ValueError: if failed to find a container model, which signifies an
          abnormal, orphaned parameter
         """
 
@@ -349,10 +349,10 @@ class ParameterMixin(TemplateModelMixin, caching.HasCachedMethods):
         cos01 specification <http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.0/cos01
         /TOSCA-Simple-Profile-YAML-v1.0-cos01.html#_Toc373867862>`__
 
-        :param name: Parameter name
+        :param name: parameter name
         :type name: basestring
-        :param value: Parameter value
-        :param description: Description (optional)
+        :param value: parameter value
+        :param description: human-readable description (optional)
         :type description: basestring
         """
 

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/modeling/models.py
----------------------------------------------------------------------
diff --git a/aria/modeling/models.py b/aria/modeling/models.py
index f2aa1ea..cf84fdb 100644
--- a/aria/modeling/models.py
+++ b/aria/modeling/models.py
@@ -14,7 +14,71 @@
 # limitations under the License.
 
 """
-Models.
+Data models.
+
+Service template models
+-----------------------
+
+.. autosummary::
+   :nosignatures:
+
+   aria.modeling.models.ServiceTemplate
+   aria.modeling.models.NodeTemplate
+   aria.modeling.models.GroupTemplate
+   aria.modeling.models.PolicyTemplate
+   aria.modeling.models.SubstitutionTemplate
+   aria.modeling.models.SubstitutionTemplateMapping
+   aria.modeling.models.RequirementTemplate
+   aria.modeling.models.RelationshipTemplate
+   aria.modeling.models.CapabilityTemplate
+   aria.modeling.models.InterfaceTemplate
+   aria.modeling.models.OperationTemplate
+   aria.modeling.models.ArtifactTemplate
+   aria.modeling.models.PluginSpecification
+
+Service instance models
+-----------------------
+
+.. autosummary::
+   :nosignatures:
+
+   aria.modeling.models.Service
+   aria.modeling.models.Node
+   aria.modeling.models.Group
+   aria.modeling.models.Policy
+   aria.modeling.models.Substitution
+   aria.modeling.models.SubstitutionMapping
+   aria.modeling.models.Relationship
+   aria.modeling.models.Capability
+   aria.modeling.models.Interface
+   aria.modeling.models.Operation
+   aria.modeling.models.Artifact
+
+Common models
+-------------
+
+.. autosummary::
+   :nosignatures:
+
+   aria.modeling.models.Output
+   aria.modeling.models.Input
+   aria.modeling.models.Configuration
+   aria.modeling.models.Property
+   aria.modeling.models.Attribute
+   aria.modeling.models.Type
+   aria.modeling.models.Metadata
+
+Orchestration models
+--------------------
+
+.. autosummary::
+   :nosignatures:
+
+   aria.modeling.models.Execution
+   aria.modeling.models.Task
+   aria.modeling.models.Log
+   aria.modeling.models.Plugin
+   aria.modeling.models.Argument
 """
 
 # pylint: disable=abstract-method
@@ -31,7 +95,8 @@ from . import (
     service_changes,
     service_common,
     orchestration,
-    mixins
+    mixins,
+    utils
 )
 
 
@@ -93,85 +158,70 @@ __all__ = (
 )
 
 
-def _clean_init_doc(cls):
-    # Make sure Sphinx doesn't grab the base constructor's docstring
-    original_init = cls.__init__
-    def init(*args, **kwargs):
-        original_init(*args, **kwargs)
-    cls.__init__ = init
-    return cls
-
-
-def _fix_doc(cls):
-    # Use the last base class's docstring
-    cls.__doc__ = cls.__bases__[-1].__doc__
-    return _clean_init_doc(cls)
-
-
 # region service template models
 
-@_fix_doc
+@utils.fix_doc
 class ServiceTemplate(aria_declarative_base, service_template.ServiceTemplateBase):
     name = Column(Text, index=True, unique=True)
 
 
-@_fix_doc
+@utils.fix_doc
 class NodeTemplate(aria_declarative_base, service_template.NodeTemplateBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class GroupTemplate(aria_declarative_base, service_template.GroupTemplateBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class PolicyTemplate(aria_declarative_base, service_template.PolicyTemplateBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class SubstitutionTemplate(aria_declarative_base, service_template.SubstitutionTemplateBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class SubstitutionTemplateMapping(aria_declarative_base,
                                   service_template.SubstitutionTemplateMappingBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class RequirementTemplate(aria_declarative_base, service_template.RequirementTemplateBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class RelationshipTemplate(aria_declarative_base, service_template.RelationshipTemplateBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class CapabilityTemplate(aria_declarative_base, service_template.CapabilityTemplateBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class InterfaceTemplate(aria_declarative_base, service_template.InterfaceTemplateBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class OperationTemplate(aria_declarative_base, service_template.OperationTemplateBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class ArtifactTemplate(aria_declarative_base, service_template.ArtifactTemplateBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class PluginSpecification(aria_declarative_base, service_template.PluginSpecificationBase):
     pass
 
@@ -180,57 +230,57 @@ class PluginSpecification(aria_declarative_base, service_template.PluginSpecific
 
 # region service instance models
 
-@_fix_doc
+@utils.fix_doc
 class Service(aria_declarative_base, service_instance.ServiceBase):
     name = Column(Text, index=True, unique=True)
 
 
-@_fix_doc
+@utils.fix_doc
 class Node(aria_declarative_base, service_instance.NodeBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class Group(aria_declarative_base, service_instance.GroupBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class Policy(aria_declarative_base, service_instance.PolicyBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class Substitution(aria_declarative_base, service_instance.SubstitutionBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class SubstitutionMapping(aria_declarative_base, service_instance.SubstitutionMappingBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class Relationship(aria_declarative_base, service_instance.RelationshipBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class Capability(aria_declarative_base, service_instance.CapabilityBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class Interface(aria_declarative_base, service_instance.InterfaceBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class Operation(aria_declarative_base, service_instance.OperationBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class Artifact(aria_declarative_base, service_instance.ArtifactBase):
     pass
 
@@ -239,17 +289,17 @@ class Artifact(aria_declarative_base, service_instance.ArtifactBase):
 
 # region service changes models
 
-@_fix_doc
+@utils.fix_doc
 class ServiceUpdate(aria_declarative_base, service_changes.ServiceUpdateBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class ServiceUpdateStep(aria_declarative_base, service_changes.ServiceUpdateStepBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class ServiceModification(aria_declarative_base, service_changes.ServiceModificationBase):
     pass
 
@@ -258,37 +308,37 @@ class ServiceModification(aria_declarative_base, service_changes.ServiceModifica
 
 # region common service models
 
-@_fix_doc
+@utils.fix_doc
 class Input(aria_declarative_base, service_common.InputBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class Configuration(aria_declarative_base, service_common.ConfigurationBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class Output(aria_declarative_base, service_common.OutputBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class Property(aria_declarative_base, service_common.PropertyBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class Attribute(aria_declarative_base, service_common.AttributeBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class Type(aria_declarative_base, service_common.TypeBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class Metadata(aria_declarative_base, service_common.MetadataBase):
     pass
 
@@ -297,27 +347,27 @@ class Metadata(aria_declarative_base, service_common.MetadataBase):
 
 # region orchestration models
 
-@_fix_doc
+@utils.fix_doc
 class Execution(aria_declarative_base, orchestration.ExecutionBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class Plugin(aria_declarative_base, orchestration.PluginBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class Task(aria_declarative_base, orchestration.TaskBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class Log(aria_declarative_base, orchestration.LogBase):
     pass
 
 
-@_fix_doc
+@utils.fix_doc
 class Argument(aria_declarative_base, orchestration.ArgumentBase):
     pass
 

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/modeling/orchestration.py
----------------------------------------------------------------------
diff --git a/aria/modeling/orchestration.py b/aria/modeling/orchestration.py
index 1c94966..a44a42d 100644
--- a/aria/modeling/orchestration.py
+++ b/aria/modeling/orchestration.py
@@ -31,7 +31,6 @@ from sqlalchemy import (
     Float,
     orm,
     PickleType)
-from sqlalchemy.ext.associationproxy import association_proxy
 from sqlalchemy.ext.declarative import declared_attr
 
 from ..orchestrator.exceptions import (TaskAbortException, TaskRetryException)
@@ -117,18 +116,15 @@ class ExecutionBase(mixins.ModelMixin):
 
     @declared_attr
     def service_name(cls):
-        """Required for use by SQLAlchemy queries"""
-        return association_proxy('service', cls.name_column_name())
+        return relationship.association_proxy('service', cls.name_column_name())
 
     @declared_attr
     def service_template(cls):
-        """Required for use by SQLAlchemy queries"""
-        return association_proxy('service', 'service_template')
+        return relationship.association_proxy('service', 'service_template')
 
     @declared_attr
     def service_template_name(cls):
-        """Required for use by SQLAlchemy queries"""
-        return association_proxy('service', 'service_template_name')
+        return relationship.association_proxy('service', 'service_template_name')
 
     # endregion
 
@@ -325,18 +321,15 @@ class TaskBase(mixins.ModelMixin):
 
     @declared_attr
     def node_name(cls):
-        """Required for use by SQLAlchemy queries"""
-        return association_proxy('node', cls.name_column_name())
+        return relationship.association_proxy('node', cls.name_column_name())
 
     @declared_attr
     def relationship_name(cls):
-        """Required for use by SQLAlchemy queries"""
-        return association_proxy('relationship', cls.name_column_name())
+        return relationship.association_proxy('relationship', cls.name_column_name())
 
     @declared_attr
     def execution_name(cls):
-        """Required for use by SQLAlchemy queries"""
-        return association_proxy('execution', cls.name_column_name())
+        return relationship.association_proxy('execution', cls.name_column_name())
 
     # endregion
 

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/modeling/relationship.py
----------------------------------------------------------------------
diff --git a/aria/modeling/relationship.py b/aria/modeling/relationship.py
index ce0b055..55060c9 100644
--- a/aria/modeling/relationship.py
+++ b/aria/modeling/relationship.py
@@ -21,6 +21,7 @@ ARIA modeling relationship module
 
 from sqlalchemy.orm import relationship, backref
 from sqlalchemy.orm.collections import attribute_mapped_collection
+from sqlalchemy.ext.associationproxy import association_proxy as original_association_proxy
 from sqlalchemy import (
     Column,
     ForeignKey,
@@ -48,9 +49,9 @@ def foreign_key(other_table, nullable=False):
 
     *This utility method should only be used during class creation.*
 
-    :param other_table: Other table name
+    :param other_table: other table name
     :type other_table: basestring
-    :param nullable: True to allow null values (meaning that there is no relationship)
+    :param nullable: ``True`` to allow null values (meaning that there is no relationship)
     :type nullable: bool
     """
 
@@ -68,9 +69,9 @@ def one_to_one_self(model_class, fk):
 
     *This utility method should only be used during class creation.*
 
-    :param model_class: The class in which this relationship will be declared
+    :param model_class: class in which this relationship will be declared
     :type model_class: type
-    :param fk: Foreign key name
+    :param fk: foreign key name
     :type fk: basestring
     """
 
@@ -104,12 +105,12 @@ def one_to_many_self(model_class, fk, dict_key=None):
 
     *This utility method should only be used during class creation.*
 
-    :param model_class: The class in which this relationship will be declared
+    :param model_class: class in which this relationship will be declared
     :type model_class: type
     :param fk: Foreign key name
     :type fk: basestring
-    :param dict_key: If set the value will be a dict with this key as the dict key; otherwise will
-                     be a list
+    :param dict_key: if set the value will be a dict with this key as the dict key; otherwise will
+     be a list
     :type dict_key: basestring
     """
     return _relationship(
@@ -139,17 +140,17 @@ def one_to_one(model_class,
 
     *This utility method should only be used during class creation.*
 
-    :param model_class: The class in which this relationship will be declared
+    :param model_class: class in which this relationship will be declared
     :type model_class: type
-    :param other_table: Other table name
+    :param other_table: other table name
     :type other_table: basestring
-    :param fk: Foreign key name at our table (no need specify if there's no ambiguity)
+    :param fk: foreign key name at our table (no need specify if there's no ambiguity)
     :type fk: basestring
-    :param other_fk: Foreign key name at the other table (no need specify if there's no ambiguity)
+    :param other_fk: foreign key name at the other table (no need specify if there's no ambiguity)
     :type other_fk: basestring
-    :param back_populates: Override name of matching many-to-many property at other table; set to
-                       false to disable
-    :type back_populates: basestring|bool
+    :param back_populates: override name of matching many-to-many property at other table; set to
+     ``False`` to disable
+    :type back_populates: basestring or bool
     """
     backref_kwargs = None
     if back_populates is not NO_BACK_POP:
@@ -183,18 +184,18 @@ def one_to_many(model_class,
 
     *This utility method should only be used during class creation.*
 
-    :param model_class: The class in which this relationship will be declared
+    :param model_class: class in which this relationship will be declared
     :type model_class: type
-    :param child_table: Child table name
+    :param child_table: child table name
     :type child_table: basestring
-    :param child_fk: Foreign key name at the child table (no need specify if there's no ambiguity)
+    :param child_fk: foreign key name at the child table (no need specify if there's no ambiguity)
     :type child_fk: basestring
-    :param dict_key: If set the value will be a dict with this key as the dict key; otherwise will
-                     be a list
+    :param dict_key: if set the value will be a dict with this key as the dict key; otherwise will
+     be a list
     :type dict_key: basestring
-    :param back_populates: Override name of matching many-to-one property at child table; set to
-                           false to disable
-    :type back_populates: basestring|bool
+    :param back_populates: override name of matching many-to-one property at child table; set to
+     ``false`` to disable
+    :type back_populates: basestring or bool
     """
     rel_kwargs = rel_kwargs or {}
     rel_kwargs.setdefault('cascade', 'all')
@@ -228,15 +229,15 @@ def many_to_one(model_class,
 
     *This utility method should only be used during class creation.*
 
-    :param model_class: The class in which this relationship will be declared
+    :param model_class: class in which this relationship will be declared
     :type model_class: type
-    :param parent_table: Parent table name
+    :param parent_table: parent table name
     :type parent_table: basestring
-    :param fk: Foreign key name at our table (no need specify if there's no ambiguity)
+    :param fk: foreign key name at our table (no need specify if there's no ambiguity)
     :type fk: basestring
-    :param back_populates: Override name of matching one-to-many property at parent table; set to
-                            false to disable
-    :type back_populates: basestring|bool
+    :param back_populates: override name of matching one-to-many property at parent table; set to
+     ``False`` to disable
+    :type back_populates: basestring or bool
     """
     if back_populates is None:
         back_populates = formatting.pluralize(model_class.__tablename__)
@@ -267,18 +268,18 @@ def many_to_many(model_class,
 
     *This utility method should only be used during class creation.*
 
-    :param model_class: The class in which this relationship will be declared
+    :param model_class: class in which this relationship will be declared
     :type model_class: type
-    :param other_table: Parent table name
+    :param other_table: parent table name
     :type other_table: basestring
-    :param prefix: Optional prefix for extra table name as well as for ``other_property``
+    :param prefix: optional prefix for extra table name as well as for ``other_property``
     :type prefix: basestring
-    :param dict_key: If set the value will be a dict with this key as the dict key; otherwise will
-                     be a list
+    :param dict_key: if set the value will be a dict with this key as the dict key; otherwise will
+     be a list
     :type dict_key: basestring
-    :param other_property: Override name of matching many-to-many property at other table; set to
-                           false to disable
-    :type other_property: basestring|bool
+    :param other_property: override name of matching many-to-many property at other table; set to
+     ``False`` to disable
+    :type other_property: basestring or bool
     """
 
     this_table = model_class.__tablename__
@@ -313,6 +314,21 @@ def many_to_many(model_class,
     )
 
 
+def association_proxy(*args, **kwargs):
+    if 'type' in kwargs:
+        type_ = kwargs.get('type')
+        del kwargs['type']
+    else:
+        type_ = ':obj:`basestring`'
+    proxy = original_association_proxy(*args, **kwargs)
+    proxy.__doc__ = """
+    Internal. For use in SQLAlchemy queries.
+
+    :type: {0}
+    """.format(type_)
+    return proxy
+
+
 def _relationship(model_class,
                   other_table_name,
                   back_populates=None,

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/modeling/service_changes.py
----------------------------------------------------------------------
diff --git a/aria/modeling/service_changes.py b/aria/modeling/service_changes.py
index b536443..061262a 100644
--- a/aria/modeling/service_changes.py
+++ b/aria/modeling/service_changes.py
@@ -27,7 +27,6 @@ from sqlalchemy import (
     DateTime,
     Enum,
 )
-from sqlalchemy.ext.associationproxy import association_proxy
 from sqlalchemy.ext.declarative import declared_attr
 
 from .types import (List, Dict)
@@ -56,13 +55,11 @@ class ServiceUpdateBase(ModelMixin):
 
     @declared_attr
     def execution_name(cls):
-        """Required for use by SQLAlchemy queries"""
-        return association_proxy('execution', cls.name_column_name())
+        return relationship.association_proxy('execution', cls.name_column_name())
 
     @declared_attr
     def service_name(cls):
-        """Required for use by SQLAlchemy queries"""
-        return association_proxy('service', cls.name_column_name())
+        return relationship.association_proxy('service', cls.name_column_name())
 
     # endregion
 
@@ -144,8 +141,7 @@ class ServiceUpdateStepBase(ModelMixin):
 
     @declared_attr
     def service_update_name(cls):
-        """Required for use by SQLAlchemy queries"""
-        return association_proxy('service_update', cls.name_column_name())
+        return relationship.association_proxy('service_update', cls.name_column_name())
 
     # endregion
 
@@ -228,8 +224,7 @@ class ServiceModificationBase(ModelMixin):
 
     @declared_attr
     def service_name(cls):
-        """Required for use by SQLAlchemy queries"""
-        return association_proxy('service', cls.name_column_name())
+        return relationship.association_proxy('service', cls.name_column_name())
 
     # endregion
 

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/modeling/service_instance.py
----------------------------------------------------------------------
diff --git a/aria/modeling/service_instance.py b/aria/modeling/service_instance.py
index fa79091..de12ea2 100644
--- a/aria/modeling/service_instance.py
+++ b/aria/modeling/service_instance.py
@@ -27,7 +27,6 @@ from sqlalchemy import (
     Boolean
 )
 from sqlalchemy import DateTime
-from sqlalchemy.ext.associationproxy import association_proxy
 from sqlalchemy.ext.declarative import declared_attr
 from sqlalchemy.ext.orderinglist import ordering_list
 
@@ -63,8 +62,7 @@ class ServiceBase(InstanceModelMixin):
 
     @declared_attr
     def service_template_name(cls):
-        """Required for use by SQLAlchemy queries"""
-        return association_proxy('service_template', 'name')
+        return relationship.association_proxy('service_template', 'name', type=':obj:`basestring`')
 
     # endregion
 
@@ -404,13 +402,11 @@ class NodeBase(InstanceModelMixin):
 
     @declared_attr
     def service_name(cls):
-        """Required for use by SQLAlchemy queries"""
-        return association_proxy('service', 'name')
+        return relationship.association_proxy('service', 'name', type=':obj:`basestring`')
 
     @declared_attr
     def node_template_name(cls):
-        """Required for use by SQLAlchemy queries"""
-        return association_proxy('node_template', 'name')
+        return relationship.association_proxy('node_template', 'name', type=':obj:`basestring`')
 
     # endregion
 
@@ -1323,13 +1319,11 @@ class RelationshipBase(InstanceModelMixin):
 
     @declared_attr
     def source_node_name(cls):
-        """Required for use by SQLAlchemy queries"""
-        return association_proxy('source_node', 'name')
+        return relationship.association_proxy('source_node', 'name')
 
     @declared_attr
     def target_node_name(cls):
-        """Required for use by SQLAlchemy queries"""
-        return association_proxy('target_node', 'name')
+        return relationship.association_proxy('target_node', 'name')
 
     # endregion
 

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/modeling/service_template.py
----------------------------------------------------------------------
diff --git a/aria/modeling/service_template.py b/aria/modeling/service_template.py
index 70ec831..c722400 100644
--- a/aria/modeling/service_template.py
+++ b/aria/modeling/service_template.py
@@ -32,7 +32,6 @@ from sqlalchemy import (
     PickleType
 )
 from sqlalchemy.ext.declarative import declared_attr
-from sqlalchemy.ext.associationproxy import association_proxy
 
 from ..parser import validation
 from ..parser.consumption import ConsumptionContext
@@ -473,13 +472,11 @@ class NodeTemplateBase(TemplateModelMixin):
 
     @declared_attr
     def service_template_name(cls):
-        """Required for use by SQLAlchemy queries"""
-        return association_proxy('service_template', 'name')
+        return relationship.association_proxy('service_template', 'name')
 
     @declared_attr
     def type_name(cls):
-        """Required for use by SQLAlchemy queries"""
-        return association_proxy('type', 'name')
+        return relationship.association_proxy('type', 'name')
 
     # endregion
 

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/modeling/utils.py
----------------------------------------------------------------------
diff --git a/aria/modeling/utils.py b/aria/modeling/utils.py
index a60a7a5..5193cd9 100644
--- a/aria/modeling/utils.py
+++ b/aria/modeling/utils.py
@@ -76,13 +76,12 @@ def merge_parameter_values(parameter_values, declared_parameters, model_cls):
     :type declared_parameters: {:obj:`basestring`: :class:`~aria.modeling.models.Parameter`}
     :return: the merged parameters
     :rtype: {:obj:`basestring`: :class:`~aria.modeling.models.Parameter`}
-    :raises aria.modeling.exceptions.UndeclaredParametersException: if a key in ``parameter_values``
-            does not exist in ``declared_parameters``
-    :raises aria.modeling.exceptions.MissingRequiredParametersException: if a key in
-            ``declared_parameters`` does not exist in ``parameter_values`` and also has no default
-            value
-    :raises aria.modeling.exceptions.ParametersOfWrongTypeException: if a value in
-            ``parameter_values`` does not match its type in ``declared_parameters``
+    :raises ~aria.modeling.exceptions.UndeclaredParametersException: if a key in
+     ``parameter_values`` does not exist in ``declared_parameters``
+    :raises ~aria.modeling.exceptions.MissingRequiredParametersException: if a key in
+     ``declared_parameters`` does not exist in ``parameter_values`` and also has no default value
+    :raises ~aria.modeling.exceptions.ParametersOfWrongTypeException: if a value in
+      ``parameter_values`` does not match its type in ``declared_parameters``
     """
 
     parameter_values = parameter_values or {}
@@ -215,6 +214,22 @@ def dump_interfaces(interfaces, name='Interfaces'):
 class classproperty(object):                                                                        # pylint: disable=invalid-name
     def __init__(self, f):
         self._func = f
+        self.__doct__ = f.__doc__
 
     def __get__(self, instance, owner):
         return self._func(owner)
+
+
+def fix_doc(cls):
+    """
+    Class decorator to use the last base class's docstring and make sure Sphinx doesn't grab the
+    base constructor's docstring.
+    """
+    original_init = cls.__init__
+    def init(*args, **kwargs):
+        original_init(*args, **kwargs)
+
+    cls.__init__ = init
+    cls.__doc__ = cls.__bases__[-1].__doc__
+
+    return cls

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/__init__.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/__init__.py b/aria/orchestrator/__init__.py
index 1b9f25b..24fee9e 100644
--- a/aria/orchestrator/__init__.py
+++ b/aria/orchestrator/__init__.py
@@ -14,7 +14,7 @@
 # limitations under the License.
 
 """
-ARIA orchestrator package
+Orchestrator package.
 """
 
 from .decorators import (

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/context/__init__.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/context/__init__.py b/aria/orchestrator/context/__init__.py
index ad89b13..a87828d 100644
--- a/aria/orchestrator/context/__init__.py
+++ b/aria/orchestrator/context/__init__.py
@@ -14,7 +14,7 @@
 # limitations under the License.
 
 """
-Provides contexts to workflow and operation
+Contexts for workflows and operations.
 """
 
 from . import workflow, operation

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/context/common.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/context/common.py b/aria/orchestrator/context/common.py
index f4df317..f400142 100644
--- a/aria/orchestrator/context/common.py
+++ b/aria/orchestrator/context/common.py
@@ -14,8 +14,9 @@
 # limitations under the License.
 
 """
-A common context for both workflow and operation
+Common code for contexts.
 """
+
 import logging
 from contextlib import contextmanager
 from functools import partial
@@ -33,7 +34,7 @@ from ...utils.uuid import generate_uuid
 
 class BaseContext(object):
     """
-    Base context object for workflow and operation
+    Base class for contexts.
     """
 
     INSTRUMENTATION_FIELDS = (
@@ -109,52 +110,48 @@ class BaseContext(object):
     @property
     def model(self):
         """
-        Access to the model storage
-        :return:
+        Storage model API ("MAPI").
         """
         return self._model
 
     @property
     def resource(self):
         """
-        Access to the resource storage
-        :return:
+        Storage resource API ("RAPI").
         """
         return self._resource
 
     @property
     def service_template(self):
         """
-        The blueprint model
+        Service template model.
         """
         return self.service.service_template
 
     @property
     def service(self):
         """
-        The deployment model
+        Service instance model.
         """
         return self.model.service.get(self._service_id)
 
     @property
     def name(self):
         """
-        The operation name
-        :return:
+        Operation name.
         """
         return self._name
 
     @property
     def id(self):
         """
-        The operation id
-        :return:
+        Operation ID.
         """
         return self._id
 
     def download_resource(self, destination, path=None):
         """
-        Download a blueprint resource from the resource storage
+        Download a service template resource from the storage resource API ("RAPI").
         """
         try:
             self.resource.service.download(entry_id=str(self.service.id),
@@ -167,9 +164,9 @@ class BaseContext(object):
 
     def download_resource_and_render(self, destination, path=None, variables=None):
         """
-        Download a blueprint resource from the resource storage render its content as a jinja
-        template using the provided variables. ctx is available to the template without providing it
-        explicitly.
+        Downloads a service template resource from the resource storage and renders its content as a
+        Jinja template using the provided variables. ``ctx`` is available to the template without
+        providing it explicitly.
         """
         resource_content = self.get_resource(path=path)
         resource_content = self._render_resource(resource_content=resource_content,
@@ -179,7 +176,7 @@ class BaseContext(object):
 
     def get_resource(self, path=None):
         """
-        Read a deployment resource as string from the resource storage
+        Reads a service instance resource as string from the resource storage.
         """
         try:
             return self.resource.service.read(entry_id=str(self.service.id), path=path)
@@ -189,9 +186,9 @@ class BaseContext(object):
 
     def get_resource_and_render(self, path=None, variables=None):
         """
-        Read a deployment resource as string from the resource storage and render it as a jinja
-        template using the provided variables. ctx is available to the template without providing it
-        explicitly.
+        Reads a service instance resource as string from the resource storage and renders it as a
+        Jinja template using the provided variables. ``ctx`` is available to the template without
+        providing it explicitly.
         """
         resource_content = self.get_resource(path=path)
         return self._render_resource(resource_content=resource_content, variables=variables)

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/context/exceptions.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/context/exceptions.py b/aria/orchestrator/context/exceptions.py
index fe762e1..e46e2b1 100644
--- a/aria/orchestrator/context/exceptions.py
+++ b/aria/orchestrator/context/exceptions.py
@@ -12,9 +12,11 @@
 # 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.
+
 """
-Context based exceptions
+Context exceptions.
 """
+
 from ..exceptions import OrchestratorError
 
 

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/context/operation.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/context/operation.py b/aria/orchestrator/context/operation.py
index d43b847..7d5f40c 100644
--- a/aria/orchestrator/context/operation.py
+++ b/aria/orchestrator/context/operation.py
@@ -14,7 +14,7 @@
 # limitations under the License.
 
 """
-Workflow and operation contexts
+Operation contexts.
 """
 
 import threading
@@ -27,7 +27,7 @@ from . import common
 
 class BaseOperationContext(common.BaseContext):
     """
-    Context object used during operation creation and execution
+    Base class for contexts used during operation creation and execution.
     """
 
     def __init__(self, task_id, actor_id, **kwargs):
@@ -116,7 +116,7 @@ class BaseOperationContext(common.BaseContext):
 
 class NodeOperationContext(BaseOperationContext):
     """
-    Context for node based operations.
+    Context for node operations.
     """
 
     @property
@@ -138,7 +138,7 @@ class NodeOperationContext(BaseOperationContext):
 
 class RelationshipOperationContext(BaseOperationContext):
     """
-    Context for relationship based operations.
+    Context for relationship operations.
     """
 
     @property

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/context/toolbelt.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/context/toolbelt.py b/aria/orchestrator/context/toolbelt.py
index b5a54a9..a2e1122 100644
--- a/aria/orchestrator/context/toolbelt.py
+++ b/aria/orchestrator/context/toolbelt.py
@@ -12,8 +12,9 @@
 # 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.
+
 """
-Provides with different tools for operations.
+Tools for operations.
 """
 
 from . import operation
@@ -21,7 +22,7 @@ from . import operation
 
 class NodeToolBelt(object):
     """
-    Node operation related tool belt
+    Node operation tool belt.
     """
     def __init__(self, operation_context):
         self._op_context = operation_context
@@ -38,7 +39,7 @@ class NodeToolBelt(object):
 
 class RelationshipToolBelt(object):
     """
-    Relationship operation related tool belt
+    Relationship operation tool belt.
     """
     def __init__(self, operation_context):
         self._op_context = operation_context
@@ -46,9 +47,9 @@ class RelationshipToolBelt(object):
 
 def toolbelt(operation_context):
     """
-    Get a toolbelt according to the current operation executor
+    Get a toolbelt from to the current operation executor.
+
     :param operation_context:
-    :return:
     """
     if isinstance(operation_context, operation.NodeOperationContext):
         return NodeToolBelt(operation_context)

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/context/workflow.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/context/workflow.py b/aria/orchestrator/context/workflow.py
index adcd635..670ff03 100644
--- a/aria/orchestrator/context/workflow.py
+++ b/aria/orchestrator/context/workflow.py
@@ -14,7 +14,7 @@
 # limitations under the License.
 
 """
-Workflow and operation contexts
+Workflow context.
 """
 
 import threading
@@ -28,7 +28,7 @@ from .common import BaseContext
 
 class WorkflowContext(BaseContext):
     """
-    Context object used during workflow creation and execution
+    Context used during workflow creation and execution.
     """
     def __init__(self,
                  workflow_name,
@@ -59,21 +59,21 @@ class WorkflowContext(BaseContext):
     @property
     def execution(self):
         """
-        The execution model
+        Execution model.
         """
         return self.model.execution.get(self._execution_id)
 
     @execution.setter
     def execution(self, value):
         """
-        Store the execution in the model storage
+        Stores the execution in the storage model API ("MAPI").
         """
         self.model.execution.put(value)
 
     @property
     def node_templates(self):
         """
-        Iterator over nodes
+        Iterates over nodes templates.
         """
         key = 'service_{0}'.format(self.model.node_template.model_cls.name_column_name())
 
@@ -86,7 +86,7 @@ class WorkflowContext(BaseContext):
     @property
     def nodes(self):
         """
-        Iterator over node instances
+        Iterates over nodes.
         """
         key = 'service_{0}'.format(self.model.node.model_cls.name_column_name())
         return self.model.node.iter(
@@ -121,7 +121,7 @@ class WorkflowContext(BaseContext):
 
 class _CurrentContext(threading.local):
     """
-    Provides thread-level context, which sugarcoats the task mapi.
+    Provides a thread-level context, with sugar for the task MAPI.
     """
 
     def __init__(self):
@@ -133,9 +133,7 @@ class _CurrentContext(threading.local):
 
     def get(self):
         """
-        Retrieves the current workflow context
-        :return: the workflow context
-        :rtype: WorkflowContext
+        Retrieves the current workflow context.
         """
         if self._workflow_context is not None:
             return self._workflow_context
@@ -144,9 +142,7 @@ class _CurrentContext(threading.local):
     @contextmanager
     def push(self, workflow_context):
         """
-        Switches the current context to the provided context
-        :param workflow_context: the context to switch to.
-        :yields: the current context
+        Switches the current context to the provided context.
         """
         prev_workflow_context = self._workflow_context
         self._set(workflow_context)

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/decorators.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/decorators.py b/aria/orchestrator/decorators.py
index 09a2167..4b163d6 100644
--- a/aria/orchestrator/decorators.py
+++ b/aria/orchestrator/decorators.py
@@ -14,7 +14,7 @@
 # limitations under the License.
 
 """
-Workflow and operation decorators
+Workflow and operation decorators.
 """
 
 from functools import partial, wraps

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/events.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/events.py b/aria/orchestrator/events.py
index aa1b5bc..ef84e5d 100644
--- a/aria/orchestrator/events.py
+++ b/aria/orchestrator/events.py
@@ -14,10 +14,7 @@
 # limitations under the License.
 
 """
-ARIA's events Sub-Package
-Path: aria.events
-
-Events package provides events mechanism for different executions in aria.
+Orchestrator events.
 """
 
 from blinker import signal

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/exceptions.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/exceptions.py b/aria/orchestrator/exceptions.py
index 71b6401..384458f 100644
--- a/aria/orchestrator/exceptions.py
+++ b/aria/orchestrator/exceptions.py
@@ -12,9 +12,11 @@
 # 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.
+
 """
-Orchestrator based exceptions
+Orchestrator exceptions.
 """
+
 from aria.exceptions import AriaError
 
 

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/execution_plugin/__init__.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/execution_plugin/__init__.py b/aria/orchestrator/execution_plugin/__init__.py
index 3624264..d15de99 100644
--- a/aria/orchestrator/execution_plugin/__init__.py
+++ b/aria/orchestrator/execution_plugin/__init__.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Execution plugin package.
+"""
+
 from contextlib import contextmanager
 from . import instantiation
 

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/execution_plugin/common.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/execution_plugin/common.py b/aria/orchestrator/execution_plugin/common.py
index 32e4575..ce6746c 100644
--- a/aria/orchestrator/execution_plugin/common.py
+++ b/aria/orchestrator/execution_plugin/common.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Execution plugin utilities.
+"""
+
 import json
 import os
 import tempfile
@@ -52,21 +56,23 @@ def download_script(ctx, script_path):
 
 def create_process_config(script_path, process, operation_kwargs, quote_json_env_vars=False):
     """
-    update a process with it's environment variables, and return it.
+    Updates a process with its environment variables, and return it.
+
+    Gets a dict representing a process and a dict representing the environment variables. Converts
+    each environment variable to a format of::
+
+        <string representing the name of the variable>:
+        <json formatted string representing the value of the variable>.
 
-    Get a dict representing a process and a dict representing the environment
-    variables. Convert each environment variable to a format of
-    <string representing the name of the variable> :
-    <json formatted string representing the value of the variable>.
-    Finally, update the process with the newly formatted environment variables,
-    and return the process.
+    Finally, updates the process with the newly formatted environment variables, and return the
+    process.
 
-    :param process: a dict representing a process
+    :param process: dict representing a process
     :type process: dict
-    :param operation_kwargs: a dict representing environment variables that
-    should exist in the process' running environment.
+    :param operation_kwargs: dict representing environment variables that should exist in the
+     process's running environment.
     :type operation_kwargs: dict
-    :return: the process updated with its environment variables.
+    :return: process updated with its environment variables
     :rtype: dict
     """
     process = process or {}

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/execution_plugin/constants.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/execution_plugin/constants.py b/aria/orchestrator/execution_plugin/constants.py
index 0b54dbe..8082e95 100644
--- a/aria/orchestrator/execution_plugin/constants.py
+++ b/aria/orchestrator/execution_plugin/constants.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Execution plugin constants.
+"""
+
 from . import exceptions
 
 # related to local

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/execution_plugin/ctx_proxy/__init__.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/execution_plugin/ctx_proxy/__init__.py b/aria/orchestrator/execution_plugin/ctx_proxy/__init__.py
index 7571c15..46c8cf1 100644
--- a/aria/orchestrator/execution_plugin/ctx_proxy/__init__.py
+++ b/aria/orchestrator/execution_plugin/ctx_proxy/__init__.py
@@ -13,4 +13,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+``ctx`` proxy.
+"""
+
 from . import server, client

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/execution_plugin/ctx_proxy/client.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/execution_plugin/ctx_proxy/client.py b/aria/orchestrator/execution_plugin/ctx_proxy/client.py
index f7f56aa..1310c21 100644
--- a/aria/orchestrator/execution_plugin/ctx_proxy/client.py
+++ b/aria/orchestrator/execution_plugin/ctx_proxy/client.py
@@ -14,6 +14,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+``ctx`` proxy client implementation.
+"""
+
 import argparse
 import json
 import os

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/execution_plugin/ctx_proxy/server.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/execution_plugin/ctx_proxy/server.py b/aria/orchestrator/execution_plugin/ctx_proxy/server.py
index 50d4c3a..0a2a606 100644
--- a/aria/orchestrator/execution_plugin/ctx_proxy/server.py
+++ b/aria/orchestrator/execution_plugin/ctx_proxy/server.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+``ctx`` proxy server implementation.
+"""
+
 import collections
 import json
 import re

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/execution_plugin/environment_globals.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/execution_plugin/environment_globals.py b/aria/orchestrator/execution_plugin/environment_globals.py
index 27311f0..6dec293 100644
--- a/aria/orchestrator/execution_plugin/environment_globals.py
+++ b/aria/orchestrator/execution_plugin/environment_globals.py
@@ -13,41 +13,38 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Utilities for managing globals for the environment.
+"""
 
 def create_initial_globals(path):
-    """ emulates a `globals()` call in a freshly loaded module
-
-    The implementation of this function is likely to raise a couple of
-    questions. If you read the implementation and nothing bothered you, feel
-    free to skip the rest of this docstring.
-
-    First, why is this function in its own module and not, say, in the same
-    module of the other environment-related functions?
-    Second, why is it implemented in such a way that copies the globals, then
-    deletes the item that represents this function, and then changes some
-    other entries?
-
-    Well, these two questions can be answered with one (elaborate) explanation.
-    If this function was in the same module with the other environment-related
-    functions, then we would have had to delete more items in globals than just
-    `create_initial_globals`. That is because all of the other function names
-    would also be in globals, and since there is no built-in mechanism that
-    return the name of the user-defined objects, this approach is quite an
-    overkill.
-
-    - But why do we rely on the copy-existing-globals-and-delete-entries
-    method, when it seems to force us to put `create_initial_globals` in its
-    own file?
-
-    Well, because there is no easier method of creating globals of a newly
-    loaded module.
-
-    - How about hard coding a 'global' dict? It seems that there are very few
-    entries: __doc__, __file__, __name__, __package__ (but don't forget
-    __builtins__).
-
-    That would be coupling our implementation to a specific `globals`
-    implementation. What if `globals` were to change?
+    """
+    Emulates a ``globals()`` call in a freshly loaded module.
+
+    The implementation of this function is likely to raise a couple of questions. If you read the
+    implementation and nothing bothered you, feel free to skip the rest of this docstring.
+
+    First, why is this function in its own module and not, say, in the same module of the other
+    environment-related functions? Second, why is it implemented in such a way that copies the
+    globals, then deletes the item that represents this function, and then changes some other
+    entries?
+
+    Well, these two questions can be answered with one (elaborate) explanation. If this function was
+    in the same module with the other environment-related functions, then we would have had to
+    delete more items in globals than just ``create_initial_globals``. That is because all of the
+    other function names would also be in globals, and since there is no built-in mechanism that
+    return the name of the user-defined objects, this approach is quite an overkill.
+
+    *But why do we rely on the copy-existing-globals-and-delete-entries method, when it seems to
+    force us to put ``create_initial_globals`` in its own file?*
+
+    Well, because there is no easier method of creating globals of a newly loaded module.
+
+    *How about hard coding a ``globals`` dict? It seems that there are very few entries:
+    ``__doc__``, ``__file__``, ``__name__``, ``__package__`` (but don't forget ``__builtins__``).*
+
+    That would be coupling our implementation to a specific ``globals`` implementation. What if
+    ``globals`` were to change?
     """
     copied_globals = globals().copy()
     copied_globals.update({

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/execution_plugin/exceptions.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/execution_plugin/exceptions.py b/aria/orchestrator/execution_plugin/exceptions.py
index 4641c80..f201fae 100644
--- a/aria/orchestrator/execution_plugin/exceptions.py
+++ b/aria/orchestrator/execution_plugin/exceptions.py
@@ -13,9 +13,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Execution plugin exceptions.
+"""
 
 class ProcessException(Exception):
-    """Raised when local scripts and remote ssh commands fail"""
+    """
+    Raised when local scripts and remote SSH commands fail.
+    """
 
     def __init__(self, stderr=None, stdout=None, command=None, exit_code=None):
         super(ProcessException, self).__init__(stderr)
@@ -26,11 +31,15 @@ class ProcessException(Exception):
 
 
 class TaskException(Exception):
-    """Raised when remote ssh scripts fail"""
+    """
+    Raised when remote ssh scripts fail.
+    """
 
 
 class ScriptException(Exception):
-    """Used by the ctx proxy server when task.retry or task.abort are called by scripts"""
+    """
+    Used by the ``ctx`` proxy server when task.retry or task.abort are called by scripts.
+    """
 
     def __init__(self, message=None, retry=None, retry_interval=None):
         super(ScriptException, self).__init__(message)

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/execution_plugin/instantiation.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/execution_plugin/instantiation.py b/aria/orchestrator/execution_plugin/instantiation.py
index b067e8c..f55aa50 100644
--- a/aria/orchestrator/execution_plugin/instantiation.py
+++ b/aria/orchestrator/execution_plugin/instantiation.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Instantiation of :class:`~aria.modeling.models.Operation` models.
+"""
+
 # TODO: this module will eventually be moved to a new "aria.instantiation" package
 
 from ...utils.type import full_type_name

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/execution_plugin/local.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/execution_plugin/local.py b/aria/orchestrator/execution_plugin/local.py
index 121e582..04b9ecd 100644
--- a/aria/orchestrator/execution_plugin/local.py
+++ b/aria/orchestrator/execution_plugin/local.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Local execution of operations.
+"""
+
 import os
 import subprocess
 import threading

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/execution_plugin/operations.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/execution_plugin/operations.py b/aria/orchestrator/execution_plugin/operations.py
index 0bc8083..e8de545 100644
--- a/aria/orchestrator/execution_plugin/operations.py
+++ b/aria/orchestrator/execution_plugin/operations.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Entry point functions.
+"""
+
 from aria.orchestrator import operation
 from . import local as local_operations
 

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/execution_plugin/ssh/__init__.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/execution_plugin/ssh/__init__.py b/aria/orchestrator/execution_plugin/ssh/__init__.py
index ae1e83e..474deef 100644
--- a/aria/orchestrator/execution_plugin/ssh/__init__.py
+++ b/aria/orchestrator/execution_plugin/ssh/__init__.py
@@ -12,3 +12,7 @@
 # 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.
+
+"""
+Remote execution of operations over SSH.
+"""

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/execution_plugin/ssh/operations.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/execution_plugin/ssh/operations.py b/aria/orchestrator/execution_plugin/ssh/operations.py
index 7147a30..c40e783 100644
--- a/aria/orchestrator/execution_plugin/ssh/operations.py
+++ b/aria/orchestrator/execution_plugin/ssh/operations.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Utilities for running commands remotely over SSH.
+"""
+
 import os
 import random
 import string

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/plugin.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/plugin.py b/aria/orchestrator/plugin.py
index 8fbcf5a..756a28e 100644
--- a/aria/orchestrator/plugin.py
+++ b/aria/orchestrator/plugin.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Plugin management.
+"""
+
 import os
 import tempfile
 import subprocess
@@ -32,7 +36,7 @@ class PluginManager(object):
 
     def __init__(self, model, plugins_dir):
         """
-        :param plugins_dir: Root directory to install plugins in.
+        :param plugins_dir: root directory in which to install plugins
         """
         self._model = model
         self._plugins_dir = plugins_dir
@@ -72,10 +76,13 @@ class PluginManager(object):
     def load_plugin(self, plugin, env=None):
         """
         Load the plugin into an environment.
+
         Loading the plugin means the plugin's code and binaries paths will be appended to the
-        environment's PATH and PYTHONPATH, thereby allowing usage of the plugin.
-        :param plugin: The plugin to load
-        :param env: The environment to load the plugin into; If `None`, os.environ will be used.
+        environment's ``PATH`` and ``PYTHONPATH``, thereby allowing usage of the plugin.
+
+        :param plugin: plugin to load
+        :param env: environment to load the plugin into; If ``None``, :obj:`os.environ` will be
+         used
         """
         env = env or os.environ
         plugin_dir = self.get_plugin_dir(plugin)
@@ -106,9 +113,10 @@ class PluginManager(object):
     @staticmethod
     def validate_plugin(source):
         """
-        validate a plugin archive.
-        A valid plugin is a wagon (http://github.com/cloudify-cosmo/wagon)
-        in the zip format (suffix may also be .wgn).
+        Validate a plugin archive.
+
+        A valid plugin is a `wagon <http://github.com/cloudify-cosmo/wagon>`__ in the zip format
+        (suffix may also be ``.wgn``).
         """
         if not zipfile.is_zipfile(source):
             raise exceptions.InvalidPluginError(

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflow_runner.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/workflow_runner.py b/aria/orchestrator/workflow_runner.py
index 3ccb1ee..f602636 100644
--- a/aria/orchestrator/workflow_runner.py
+++ b/aria/orchestrator/workflow_runner.py
@@ -14,7 +14,7 @@
 # limitations under the License.
 
 """
-Workflow runner
+Running workflows.
 """
 
 import os
@@ -44,15 +44,16 @@ class WorkflowRunner(object):
         """
         Manages a single workflow execution on a given service.
 
-        :param workflow_name: Workflow name
-        :param service_id: Service ID
-        :param inputs: A key-value dict of inputs for the execution
-        :param model_storage: Model storage
-        :param resource_storage: Resource storage
-        :param plugin_manager: Plugin manager
-        :param executor: Executor for tasks. Defaults to a ProcessExecutor instance.
-        :param task_max_attempts: Maximum attempts of repeating each failing task
-        :param task_retry_interval: Retry interval in between retry attempts of a failing task
+        :param workflow_name: workflow name
+        :param service_id: service ID
+        :param inputs: key-value dict of inputs for the execution
+        :param model_storage: model storage API ("MAPI")
+        :param resource_storage: resource storage API ("RAPI")
+        :param plugin_manager: plugin manager
+        :param executor: executor for tasks; defaults to a
+         :class:`~aria.orchestrator.workflows.executor.process.ProcessExecutor` instance
+        :param task_max_attempts: maximum attempts of repeating each failing task
+        :param task_retry_interval: retry interval between retry attempts of a failing task
         """
 
         if not (execution_id or (workflow_name and service_id)):

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflows/__init__.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/workflows/__init__.py b/aria/orchestrator/workflows/__init__.py
index e0c979a..1f6c368 100644
--- a/aria/orchestrator/workflows/__init__.py
+++ b/aria/orchestrator/workflows/__init__.py
@@ -13,5 +13,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Workflows package.
+"""
+
 # Import required so that logging signals are registered
 from . import events_logging

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflows/api/__init__.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/workflows/api/__init__.py b/aria/orchestrator/workflows/api/__init__.py
index a3a17ee..587eee3 100644
--- a/aria/orchestrator/workflows/api/__init__.py
+++ b/aria/orchestrator/workflows/api/__init__.py
@@ -14,7 +14,7 @@
 # limitations under the License.
 
 """
-Provides API for building tasks
+Workflow API.
 """
 
 from . import task, task_graph

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflows/api/task.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/workflows/api/task.py b/aria/orchestrator/workflows/api/task.py
index c2600b0..4c518fc 100644
--- a/aria/orchestrator/workflows/api/task.py
+++ b/aria/orchestrator/workflows/api/task.py
@@ -26,7 +26,7 @@ from .. import exceptions
 
 class BaseTask(object):
     """
-    Abstract task graph task
+    Base class for tasks.
     """
 
     def __init__(self, ctx=None, **kwargs):
@@ -39,44 +39,43 @@ class BaseTask(object):
     @property
     def id(self):
         """
-        uuid4 generated id
-        :return:
+        UUID4 ID.
         """
         return self._id
 
     @property
     def workflow_context(self):
         """
-        the context of the current workflow
-        :return:
+        Context of the current workflow.
         """
         return self._workflow_context
 
 
 class OperationTask(BaseTask):
     """
-    Represents an operation task in the task graph.
+    Executes an operation.
 
     :ivar name: formatted name (includes actor type, actor name, and interface/operation names)
     :vartype name: basestring
     :ivar actor: node or relationship
-    :vartype actor: :class:`Node`|:class:`Relationship`
+    :vartype actor: :class:`~aria.modeling.models.Node` or
+     :class:`~aria.modeling.models.Relationship`
     :ivar interface_name: interface name on actor
     :vartype interface_name: basestring
     :ivar operation_name: operation name on interface
     :vartype operation_name: basestring
     :ivar plugin: plugin (or None for default plugin)
-    :vartype plugin: :class:`Plugin`
+    :vartype plugin: :class:`~aria.modeling.models.Plugin`
     :ivar function: path to Python function
     :vartype function: basestring
     :ivar arguments: arguments to send to Python function
-    :vartype arguments: {::obj:`basestring`: :class:`Argument`}
+    :vartype arguments: {:obj:`basestring`: :class:`~aria.modeling.models.Argument`}
     :ivar ignore_failure: whether to ignore failures
     :vartype ignore_failure: bool
     :ivar max_attempts: maximum number of attempts allowed in case of failure
     :vartype max_attempts: int
     :ivar retry_interval: interval between retries (in seconds)
-    :vartype retry_interval: int
+    :vartype retry_interval: float
     """
 
     NAME_FORMAT = '{interface}:{operation}@{type}:{name}'
@@ -91,7 +90,8 @@ class OperationTask(BaseTask):
                  retry_interval=None):
         """
         :param actor: node or relationship
-        :type actor: :class:`Node`|:class:`Relationship`
+        :type actor: :class:`~aria.modeling.models.Node` or
+         :class:`~aria.modeling.models.Relationship`
         :param interface_name: interface name on actor
         :type interface_name: basestring
         :param operation_name: operation name on interface
@@ -103,9 +103,9 @@ class OperationTask(BaseTask):
         :param max_attempts: override maximum number of attempts allowed in case of failure
         :type max_attempts: int
         :param retry_interval: override interval between retries (in seconds)
-        :type retry_interval: int
-        :raises aria.orchestrator.workflows.exceptions.OperationNotFoundException: if
-                ``interface_name`` and ``operation_name`` to not refer to an operation on the actor
+        :type retry_interval: float
+        :raises ~aria.orchestrator.workflows.exceptions.OperationNotFoundException: if
+         ``interface_name`` and ``operation_name`` do not refer to an operation on the actor
         """
 
         # Creating OperationTask directly should raise an error when there is no
@@ -160,14 +160,13 @@ class StubTask(BaseTask):
 
 class WorkflowTask(BaseTask):
     """
-    Represents a workflow task in the task graph
+    Executes a complete workflow.
     """
 
     def __init__(self, workflow_func, **kwargs):
         """
-        Creates a workflow based task using the workflow_func provided, and its kwargs
-        :param workflow_func: the function to run
-        :param kwargs: the kwargs that would be passed to the workflow_func
+        :param workflow_func: function to run
+        :param kwargs: kwargs that would be passed to the workflow_func
         """
         super(WorkflowTask, self).__init__(**kwargs)
         kwargs['ctx'] = self.workflow_context
@@ -176,8 +175,7 @@ class WorkflowTask(BaseTask):
     @property
     def graph(self):
         """
-        The graph constructed by the sub workflow
-        :return:
+        Graph constructed by the sub workflow.
         """
         return self._graph
 
@@ -190,13 +188,14 @@ class WorkflowTask(BaseTask):
 
 def create_task(actor, interface_name, operation_name, **kwargs):
     """
-    This helper function enables safe creation of OperationTask, if the supplied interface or
-    operation do not exist, None is returned.
-    :param actor: the actor for this task
-    :param interface_name: the name of the interface
-    :param operation_name: the name of the operation
-    :param kwargs: any additional kwargs to be passed to the task OperationTask
-    :return: and OperationTask or None (if the interface/operation does not exists)
+    Helper function that enables safe creation of :class:`OperationTask`. If the supplied interface
+    or operation do not exist, ``None`` is returned.
+
+    :param actor: actor for this task
+    :param interface_name: name of the interface
+    :param operation_name: name of the operation
+    :param kwargs: any additional kwargs to be passed to the OperationTask
+    :return: OperationTask or None (if the interface/operation does not exists)
     """
     try:
         return OperationTask(
@@ -212,13 +211,13 @@ def create_task(actor, interface_name, operation_name, **kwargs):
 def create_relationships_tasks(
         node, interface_name, source_operation_name=None, target_operation_name=None, **kwargs):
     """
-    Creates a relationship task (source and target) for all of a node_instance relationships.
-    :param basestring source_operation_name: the relationship operation name.
-    :param basestring interface_name: the name of the interface.
+    Creates a relationship task (source and target) for all of a node relationships.
+
+    :param basestring source_operation_name: relationship operation name
+    :param basestring interface_name: name of the interface
     :param source_operation_name:
     :param target_operation_name:
-    :param NodeInstance node: the source_node
-    :return:
+    :param node: source node
     """
     sub_tasks = []
     for relationship in node.outbound_relationships:
@@ -235,12 +234,11 @@ def create_relationships_tasks(
 def create_relationship_tasks(relationship, interface_name, source_operation_name=None,
                               target_operation_name=None, **kwargs):
     """
-    Creates a relationship task source and target.
-    :param Relationship relationship: the relationship instance itself
+    Creates a relationship task (source and target).
+
+    :param relationship: relationship instance itself
     :param source_operation_name:
     :param target_operation_name:
-
-    :return:
     """
     operations = []
     if source_operation_name:


Mime
View raw message