ariatosca-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From emblempar...@apache.org
Subject [15/15] incubator-ariatosca git commit: ARIA-286 Sphinx documentation for code and CLI
Date Thu, 29 Jun 2017 00:07:02 GMT
ARIA-286 Sphinx documentation for code and CLI


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

Branch: refs/heads/ARIA-286-sphinx-documentation
Commit: 3f09ecdeb45966f2f9e671ebf23892a9f6bb5c4b
Parents: 53dc64e
Author: Tal Liron <tal.liron@gmail.com>
Authored: Thu Jun 22 21:13:28 2017 -0500
Committer: Tal Liron <tal.liron@gmail.com>
Committed: Wed Jun 28 19:05:45 2017 -0500

----------------------------------------------------------------------
 aria/__init__.py                                |   14 +-
 aria/cli/__init__.py                            |    4 +
 aria/cli/color.py                               |    8 +-
 aria/cli/commands/__init__.py                   |    4 +
 aria/cli/commands/executions.py                 |   45 +-
 aria/cli/commands/logs.py                       |   22 +-
 aria/cli/commands/node_templates.py             |   21 +-
 aria/cli/commands/nodes.py                      |   23 +-
 aria/cli/commands/plugins.py                    |   38 +-
 aria/cli/commands/reset.py                      |   13 +-
 aria/cli/commands/service_templates.py          |   58 +-
 aria/cli/commands/services.py                   |   43 +-
 aria/cli/commands/workflows.py                  |   23 +-
 aria/cli/config/__init__.py                     |    4 +
 aria/cli/config/config.py                       |    3 +
 aria/cli/core/__init__.py                       |    4 +
 aria/cli/core/aria.py                           |   13 +-
 aria/cli/csar.py                                |    7 +
 aria/cli/defaults.py                            |   10 +
 aria/cli/env.py                                 |    3 +
 aria/cli/exceptions.py                          |    3 +
 aria/cli/execution_logging.py                   |    5 +
 aria/cli/helptexts.py                           |   19 +-
 aria/cli/inputs.py                              |   24 +-
 aria/cli/logger.py                              |    3 +
 aria/cli/main.py                                |   15 +-
 aria/cli/service_template_utils.py              |   64 +-
 aria/cli/table.py                               |   56 +-
 aria/cli/utils.py                               |   44 +-
 aria/core.py                                    |    4 +
 aria/exceptions.py                              |   10 +-
 aria/extension.py                               |   34 +-
 aria/logger.py                                  |   38 +-
 aria/modeling/__init__.py                       |    4 +
 aria/modeling/constraints.py                    |    5 +-
 aria/modeling/exceptions.py                     |    4 +
 aria/modeling/functions.py                      |   23 +-
 aria/modeling/mixins.py                         |  101 +-
 aria/modeling/models.py                         |  113 +-
 aria/modeling/orchestration.py                  |  612 ++++---
 aria/modeling/relationship.py                   |  120 +-
 aria/modeling/service_changes.py                |   83 +-
 aria/modeling/service_common.py                 |  364 ++--
 aria/modeling/service_instance.py               | 1527 ++++++++++-------
 aria/modeling/service_template.py               | 1562 +++++++++++-------
 aria/modeling/types.py                          |   49 +-
 aria/modeling/utils.py                          |   50 +-
 aria/orchestrator/__init__.py                   |    4 +-
 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                 |    6 +-
 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         |   72 +-
 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     |  120 ++
 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                         |    4 +
 aria/parser/consumption/__init__.py             |   31 +
 aria/parser/consumption/consumer.py             |    4 +-
 aria/parser/consumption/context.py              |   28 +-
 aria/parser/consumption/presentation.py         |    7 +-
 aria/parser/exceptions.py                       |    4 +
 aria/parser/loading/__init__.py                 |   35 +
 aria/parser/loading/context.py                  |    8 +-
 aria/parser/loading/literal.py                  |    2 +-
 aria/parser/loading/location.py                 |    8 +-
 aria/parser/loading/source.py                   |    2 +-
 aria/parser/loading/uri.py                      |    6 +-
 aria/parser/modeling/__init__.py                |    4 +
 aria/parser/modeling/context.py                 |   22 +-
 aria/parser/presentation/__init__.py            |   84 +-
 aria/parser/presentation/context.py             |   28 +-
 aria/parser/presentation/field_validators.py    |   19 +-
 aria/parser/presentation/fields.py              |   31 +-
 aria/parser/presentation/null.py                |    4 +-
 aria/parser/presentation/presentation.py        |   54 +-
 aria/parser/presentation/source.py              |    2 +-
 aria/parser/presentation/utils.py               |   12 +-
 aria/parser/reading/__init__.py                 |   23 +
 aria/parser/reading/context.py                  |    8 +-
 aria/parser/reading/locator.py                  |    4 +-
 aria/parser/reading/reader.py                   |    2 +-
 aria/parser/specification.py                    |    4 +
 aria/parser/validation/__init__.py              |    4 +
 aria/parser/validation/context.py               |   15 +-
 aria/storage/__init__.py                        |   24 +-
 aria/storage/api.py                             |   78 +-
 aria/storage/collection_instrumentation.py      |   50 +-
 aria/storage/core.py                            |   62 +-
 aria/storage/exceptions.py                      |    4 +-
 aria/storage/filesystem_rapi.py                 |   53 +-
 aria/storage/sql_mapi.py                        |  162 +-
 aria/utils/__init__.py                          |    4 +
 aria/utils/archive.py                           |    3 +
 aria/utils/argparse.py                          |    6 +-
 aria/utils/caching.py                           |    9 +-
 aria/utils/collections.py                       |   34 +-
 aria/utils/console.py                           |    4 +
 aria/utils/exceptions.py                        |    4 +
 aria/utils/file.py                              |    9 +-
 aria/utils/formatting.py                        |   33 +-
 aria/utils/http.py                              |   24 +-
 aria/utils/imports.py                           |   12 +-
 aria/utils/openclose.py                         |    6 +-
 aria/utils/plugin.py                            |    4 +
 aria/utils/process.py                           |    4 +
 aria/utils/specification.py                     |    4 +
 aria/utils/threading.py                         |   52 +-
 aria/utils/type.py                              |   16 +-
 aria/utils/uris.py                              |    8 +-
 aria/utils/uuid.py                              |   20 +-
 aria/utils/validation.py                        |    6 +-
 aria/utils/versions.py                          |   13 +-
 docs/aria.cli.rst                               |  100 ++
 docs/aria.modeling.models.rst                   |   21 +
 docs/aria.modeling.rst                          |   56 +
 docs/aria.orchestrator.context.rst              |   46 +
 ....orchestrator.execution_plugin.ctx_proxy.rst |   31 +
 docs/aria.orchestrator.execution_plugin.rst     |   56 +
 docs/aria.orchestrator.execution_plugin.ssh.rst |   31 +
 docs/aria.orchestrator.rst                      |   46 +
 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            |   51 +
 docs/aria.parser.consumption.rst                |   21 +
 docs/aria.parser.loading.rst                    |   21 +
 docs/aria.parser.modeling.rst                   |   21 +
 docs/aria.parser.presentation.rst               |   21 +
 docs/aria.parser.reading.rst                    |   21 +
 docs/aria.parser.rst                            |   31 +
 docs/aria.parser.validation.rst                 |   21 +
 docs/aria.rst                                   |   40 +
 docs/aria.storage.rst                           |   51 +
 docs/aria.utils.rst                             |  121 ++
 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/cli.rst                                    |   57 +
 docs/conf.py                                    |   86 +-
 docs/index.rst                                  |   66 +-
 docs/parser.rst                                 |   56 -
 docs/requirements.txt                           |    3 +-
 docs/rest.rst                                   |   20 +
 docs/tosca.rst                                  |   36 -
 .../simple_nfv_v1_0/presenter.py                |    8 +-
 .../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/__init__.py            |    2 -
 .../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 +-
 .../orchestrator/workflows/core/test_events.py  |    4 +-
 203 files changed, 6187 insertions(+), 3050 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/__init__.py
----------------------------------------------------------------------
diff --git a/aria/__init__.py b/aria/__init__.py
index bed1dc6..76a62ce 100644
--- a/aria/__init__.py
+++ b/aria/__init__.py
@@ -14,7 +14,7 @@
 # limitations under the License.
 
 """
-ARIA top level package
+The ARIA root package provides entry points for extension and storage initialization.
 """
 
 import sys
@@ -45,13 +45,17 @@ __all__ = (
     '__version__',
     'workflow',
     'operation',
+    'install_aria_extensions',
+    'application_model_storage',
+    'application_resource_storage'
 )
 
 
 def install_aria_extensions():
     """
-    Iterates all Python packages with names beginning with :code:`aria_extension_` and all
-    :code:`aria_extension` entry points and loads them.
+    Iterates all Python packages with names beginning with ``aria_extension_`` and all
+    ``aria_extension`` entry points and loads them.
+
     It then invokes all registered extension functions.
     """
     for loader, module_name, _ in iter_modules():
@@ -64,7 +68,7 @@ def install_aria_extensions():
 
 def application_model_storage(api, api_kwargs=None, initiator=None, initiator_kwargs=None):
     """
-    Initiate model storage
+    Initiate model storage.
     """
     return storage.ModelStorage(api_cls=api,
                                 api_kwargs=api_kwargs,
@@ -75,7 +79,7 @@ def application_model_storage(api, api_kwargs=None, initiator=None, initiator_kw
 
 def application_resource_storage(api, api_kwargs=None, initiator=None, initiator_kwargs=None):
     """
-    Initiate resource storage
+    Initiate resource storage.
     """
 
     return storage.ResourceStorage(api_cls=api,

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/__init__.py
----------------------------------------------------------------------
diff --git a/aria/cli/__init__.py b/aria/cli/__init__.py
index ae1e83e..c0ef46f 100644
--- a/aria/cli/__init__.py
+++ b/aria/cli/__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.
+
+"""
+CLI package.
+"""

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/color.py
----------------------------------------------------------------------
diff --git a/aria/cli/color.py b/aria/cli/color.py
index 5e0355a..03381ba 100644
--- a/aria/cli/color.py
+++ b/aria/cli/color.py
@@ -12,6 +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.
+
+"""
+Terminal colorization utilities.
+"""
+
 from StringIO import StringIO
 import re
 
@@ -75,8 +80,7 @@ class ColorSpec(object):
     def __init__(self, fore=None, back=None, style=None):
         """
         It is possible to provide fore, back and style arguments. each could be either
-        the color is lower case letter, or the actual color from colorama.
-
+        the color is lower case letter, or the actual color from Colorama.
         """
         self._kwargs = dict(fore=fore, back=back, style=style)
         self._str = StringIO()

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/commands/__init__.py
----------------------------------------------------------------------
diff --git a/aria/cli/commands/__init__.py b/aria/cli/commands/__init__.py
index a01a029..ba34a43 100644
--- a/aria/cli/commands/__init__.py
+++ b/aria/cli/commands/__init__.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+CLI commands package.
+"""
+
 from . import (
     executions,
     logs,

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/commands/executions.py
----------------------------------------------------------------------
diff --git a/aria/cli/commands/executions.py b/aria/cli/commands/executions.py
index 9f56ccd..ea70af5 100644
--- a/aria/cli/commands/executions.py
+++ b/aria/cli/commands/executions.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+CLI ``executions`` sub-commands.
+"""
+
 import os
 
 from .. import helptexts
@@ -27,28 +31,30 @@ from ...orchestrator.workflows.executor.dry import DryExecutor
 from ...utils import formatting
 from ...utils import threading
 
-EXECUTION_COLUMNS = ['id', 'workflow_name', 'status', 'service_name',
-                     'created_at', 'error']
+EXECUTION_COLUMNS = ('id', 'workflow_name', 'status', 'service_name',
+                     'created_at', 'error')
 
 
 @aria.group(name='executions')
 @aria.options.verbose()
 def executions():
-    """Handle workflow executions
+    """
+    Manage executions
     """
     pass
 
 
 @executions.command(name='show',
-                    short_help='Show execution information')
+                    short_help='Show information for an execution')
 @aria.argument('execution-id')
 @aria.options.verbose()
 @aria.pass_model_storage
 @aria.pass_logger
 def show(execution_id, model_storage, logger):
-    """Show information for a specific execution
+    """
+    Show information for an execution
 
-    `EXECUTION_ID` is the execution to get information on.
+    EXECUTION_ID is the unique ID of the execution.
     """
     logger.info('Showing execution {0}'.format(execution_id))
     execution = model_storage.execution.get(execution_id)
@@ -68,7 +74,7 @@ def show(execution_id, model_storage, logger):
 
 
 @executions.command(name='list',
-                    short_help='List service executions')
+                    short_help='List executions')
 @aria.options.service_name(required=False)
 @aria.options.sort_by()
 @aria.options.descending
@@ -80,10 +86,11 @@ def list(service_name,
          descending,
          model_storage,
          logger):
-    """List executions
+    """
+    List executions
 
-    If `SERVICE_NAME` is provided, list executions for that service.
-    Otherwise, list executions for all services.
+    If SERVICE_NAME is provided, list executions on that service. Otherwise, list executions on all
+    services.
     """
     if service_name:
         logger.info('Listing executions for service {0}...'.format(
@@ -102,7 +109,7 @@ def list(service_name,
 
 
 @executions.command(name='start',
-                    short_help='Execute a workflow')
+                    short_help='Start a workflow on a service')
 @aria.argument('workflow-name')
 @aria.options.service_name(required=True)
 @aria.options.inputs(help=helptexts.EXECUTION_INPUTS)
@@ -126,9 +133,12 @@ def start(workflow_name,
           resource_storage,
           plugin_manager,
           logger):
-    """Execute a workflow
+    """
+    Start a workflow on a service
 
-    `WORKFLOW_NAME` is the name of the workflow to execute (e.g. `uninstall`)
+    SERVICE_NAME is the unique name of the service.
+
+    WORKFLOW_NAME is the unique name of the workflow within the service (e.g. "uninstall").
     """
     service = model_storage.service.get_by_name(service_name)
     executor = DryExecutor() if dry else None  # use WorkflowRunner's default executor
@@ -145,7 +155,7 @@ def start(workflow_name,
 
 
 @executions.command(name='resume',
-                    short_help='Resume a workflow')
+                    short_help='Resume a stopped execution')
 @aria.argument('execution-id')
 @aria.options.inputs(help=helptexts.EXECUTION_INPUTS)
 @aria.options.dry_execution
@@ -166,6 +176,11 @@ def resume(execution_id,
            resource_storage,
            plugin_manager,
            logger):
+    """
+    Resume a stopped execution
+
+    EXECUTION_ID is the unique ID of the execution.
+    """
     executor = DryExecutor() if dry else None  # use WorkflowRunner's default executor
 
     execution = model_storage.execution.get(execution_id)
@@ -225,7 +240,7 @@ def _run_execution(workflow_runner, logger, model_storage, dry, mark_pattern):
 
 
 def _cancel_execution(workflow_runner, execution_thread, logger, log_iterator):
-    logger.info('Cancelling execution. Press Ctrl+C again to force-cancel')
+    logger.info('Cancelling execution. Press Ctrl+C again to force-cancel.')
     workflow_runner.cancel()
     while execution_thread.is_alive():
         try:

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/commands/logs.py
----------------------------------------------------------------------
diff --git a/aria/cli/commands/logs.py b/aria/cli/commands/logs.py
index 2f7f361..b751b97 100644
--- a/aria/cli/commands/logs.py
+++ b/aria/cli/commands/logs.py
@@ -12,6 +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.
+
+"""
+CLI ``logs`` sub-commands.
+"""
+
 from .. import execution_logging
 from ..logger import ModelLogIterator
 from ..core import aria
@@ -20,20 +25,24 @@ from ..core import aria
 @aria.group(name='logs')
 @aria.options.verbose()
 def logs():
-    """Show logs from workflow executions
+    """
+    Manage logs of workflow executions
     """
     pass
 
 
 @logs.command(name='list',
-              short_help='List execution logs')
+              short_help='List logs for an execution')
 @aria.argument('execution-id')
 @aria.options.verbose()
 @aria.options.mark_pattern()
 @aria.pass_model_storage
 @aria.pass_logger
 def list(execution_id, mark_pattern, model_storage, logger):
-    """Display logs for an execution
+    """
+    List logs for an execution
+
+    EXECUTION_ID is the unique ID of the execution.
     """
     logger.info('Listing logs for execution id {0}'.format(execution_id))
     log_iterator = ModelLogIterator(model_storage, execution_id)
@@ -45,15 +54,16 @@ def list(execution_id, mark_pattern, model_storage, logger):
 
 
 @logs.command(name='delete',
-              short_help='Delete execution logs')
+              short_help='Delete logs of an execution')
 @aria.argument('execution-id')
 @aria.options.verbose()
 @aria.pass_model_storage
 @aria.pass_logger
 def delete(execution_id, model_storage, logger):
-    """Delete logs of an execution
+    """
+    Delete logs of an execution
 
-    `EXECUTION_ID` is the execution logs to delete.
+    EXECUTION_ID is the unique ID of the execution.
     """
     logger.info('Deleting logs for execution id {0}'.format(execution_id))
     logs_list = model_storage.log.list(filters=dict(execution_fk=execution_id))

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/commands/node_templates.py
----------------------------------------------------------------------
diff --git a/aria/cli/commands/node_templates.py b/aria/cli/commands/node_templates.py
index 50c755e..ec160d2 100644
--- a/aria/cli/commands/node_templates.py
+++ b/aria/cli/commands/node_templates.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+CLI ``node-templates`` sub-commands.
+"""
+
 from .. import table
 from .. import utils
 from ..core import aria
@@ -24,22 +28,24 @@ NODE_TEMPLATE_COLUMNS = ['id', 'name', 'description', 'service_template_name', '
 @aria.group(name='node-templates')
 @aria.options.verbose()
 def node_templates():
-    """Handle a service template's node templates
+    """
+    Manages stored service templates' node templates
     """
     pass
 
 
 @node_templates.command(name='show',
-                        short_help='Show node information')
+                        short_help='Show information for a stored node template')
 @aria.argument('node-template-id')
 # @aria.options.service_template_name(required=True)
 @aria.options.verbose()
 @aria.pass_model_storage
 @aria.pass_logger
 def show(node_template_id, model_storage, logger):
-    """Show information for a specific node of a specific service template
+    """
+    Show information for a stored node template
 
-    `NODE_TEMPLATE_ID` is the node id to get information on.
+    NODE_TEMPLATE_ID is the unique node template ID.
     """
     logger.info('Showing node template {0}'.format(node_template_id))
     node_template = model_storage.node_template.get(node_template_id)
@@ -64,7 +70,7 @@ def show(node_template_id, model_storage, logger):
 
 
 @node_templates.command(name='list',
-                        short_help='List node templates for a service template')
+                        short_help='List stored node templates')
 @aria.options.service_template_name()
 @aria.options.sort_by('service_template_name')
 @aria.options.descending
@@ -72,9 +78,10 @@ def show(node_template_id, model_storage, logger):
 @aria.pass_model_storage
 @aria.pass_logger
 def list(service_template_name, sort_by, descending, model_storage, logger):
-    """List node templates
+    """
+    List stored node templates
 
-    If `SERVICE_TEMPLATE_NAME` is provided, list nodes for that service template.
+    If SERVICE_TEMPLATE_NAME is provided, list node templates for that stored service template.
     Otherwise, list node templates for all service templates.
     """
     if service_template_name:

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/commands/nodes.py
----------------------------------------------------------------------
diff --git a/aria/cli/commands/nodes.py b/aria/cli/commands/nodes.py
index 1bbefe6..30f1dd4 100644
--- a/aria/cli/commands/nodes.py
+++ b/aria/cli/commands/nodes.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+CLI ``nodes`` sub-commands.
+"""
+
 from .. import table
 from .. import utils
 from ..core import aria
@@ -24,21 +28,23 @@ NODE_COLUMNS = ['id', 'name', 'service_name', 'node_template_name', 'state']
 @aria.group(name='nodes')
 @aria.options.verbose()
 def nodes():
-    """Handle a service's nodes
+    """
+    Manage services' nodes
     """
     pass
 
 
 @nodes.command(name='show',
-               short_help='Show node information')
+               short_help='Show information for a node')
 @aria.argument('node_id')
 @aria.options.verbose()
 @aria.pass_model_storage
 @aria.pass_logger
 def show(node_id, model_storage, logger):
-    """Showing information for a specific node
+    """
+    Show information for a node
 
-    `NODE_ID` is the id of the node to get information on.
+    NODE_ID is the unique node ID.
     """
     logger.info('Showing node {0}'.format(node_id))
     node = model_storage.node.get(node_id)
@@ -55,7 +61,7 @@ def show(node_id, model_storage, logger):
 
 
 @nodes.command(name='list',
-               short_help='List node for a service')
+               short_help='List node')
 @aria.options.service_name(required=False)
 @aria.options.sort_by('service_name')
 @aria.options.descending
@@ -67,10 +73,11 @@ def list(service_name,
          descending,
          model_storage,
          logger):
-    """List nodes
+    """
+    List nodes
 
-    If `SERVICE_NAME` is provided, list nodes for that service.
-    Otherwise, list nodes for all services.
+    If SERVICE_NAME is provided, list nodes for that service. Otherwise, list nodes for all
+    services.
     """
     if service_name:
         logger.info('Listing nodes for service {0}...'.format(service_name))

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/commands/plugins.py
----------------------------------------------------------------------
diff --git a/aria/cli/commands/plugins.py b/aria/cli/commands/plugins.py
index 670288e..b5d68a2 100644
--- a/aria/cli/commands/plugins.py
+++ b/aria/cli/commands/plugins.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+CLI ``plugins`` sub-commands.
+"""
+
 from .. import table
 from .. import utils
 from ..core import aria
@@ -25,24 +29,26 @@ PLUGIN_COLUMNS = ['id', 'package_name', 'package_version', 'supported_platform',
 @aria.group(name='plugins')
 @aria.options.verbose()
 def plugins():
-    """Handle plugins
+    """
+    Manage plugins
     """
     pass
 
 
 @plugins.command(name='validate',
-                 short_help='Validate a plugin')
+                 short_help='Validate a plugin archive')
 @aria.argument('plugin-path')
 @aria.options.verbose()
 @aria.pass_plugin_manager
 @aria.pass_logger
 def validate(plugin_path, plugin_manager, logger):
-    """Validate a plugin archive
+    """
+    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).
+    A valid plugin is a wagon (`http://github.com/cloudify-cosmo/wagon`) in the ZIP format (suffix
+    may also be `.wgn`).
 
-    `PLUGIN_PATH` is the path to wagon archive to validate.
+    PLUGIN_PATH is the path to the wagon archive.
     """
     logger.info('Validating plugin {0}...'.format(plugin_path))
     plugin_manager.validate_plugin(plugin_path)
@@ -57,9 +63,13 @@ def validate(plugin_path, plugin_manager, logger):
 @aria.pass_plugin_manager
 @aria.pass_logger
 def install(ctx, plugin_path, plugin_manager, logger):
-    """Install a plugin
+    """
+    Install a plugin
 
-    `PLUGIN_PATH` is the path to wagon archive to install.
+    A valid plugin is a wagon (`http://github.com/cloudify-cosmo/wagon`) in the ZIP format (suffix
+    may also be `.wgn`).
+
+    PLUGIN_PATH is the path to the wagon archive.
     """
     ctx.invoke(validate, plugin_path=plugin_path)
     logger.info('Installing plugin {0}...'.format(plugin_path))
@@ -68,15 +78,16 @@ def install(ctx, plugin_path, plugin_manager, logger):
 
 
 @plugins.command(name='show',
-                 short_help='show plugin information')
+                 short_help='Show information for an installed plugin')
 @aria.argument('plugin-id')
 @aria.options.verbose()
 @aria.pass_model_storage
 @aria.pass_logger
 def show(plugin_id, model_storage, logger):
-    """Show information for a specific plugin
+    """
+    Show information for an installed plugin
 
-    `PLUGIN_ID` is the id of the plugin to show information on.
+    PLUGIN_ID is the unique installed plugin ID in this ARIA instance.
     """
     logger.info('Showing plugin {0}...'.format(plugin_id))
     plugin = model_storage.plugin.get(plugin_id)
@@ -84,14 +95,15 @@ def show(plugin_id, model_storage, logger):
 
 
 @plugins.command(name='list',
-                 short_help='List plugins')
+                 short_help='List all installed plugins')
 @aria.options.sort_by('uploaded_at')
 @aria.options.descending
 @aria.options.verbose()
 @aria.pass_model_storage
 @aria.pass_logger
 def list(sort_by, descending, model_storage, logger):
-    """List all plugins on the manager
+    """
+    List all installed plugins
     """
     logger.info('Listing all plugins...')
     plugins_list = model_storage.plugin.list(

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/commands/reset.py
----------------------------------------------------------------------
diff --git a/aria/cli/commands/reset.py b/aria/cli/commands/reset.py
index 1fe0714..c82c707 100644
--- a/aria/cli/commands/reset.py
+++ b/aria/cli/commands/reset.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+CLI ``reset`` command.
+"""
+
 from .. import helptexts
 from ..core import aria
 from ..env import env
@@ -20,7 +24,7 @@ from ..exceptions import AriaCliError
 
 
 @aria.command(name='reset',
-              short_help="Reset ARIA's working directory")
+              short_help="Reset ARIA working directory")
 @aria.options.force(help=helptexts.FORCE_RESET)
 @aria.options.reset_config
 @aria.pass_logger
@@ -28,9 +32,10 @@ from ..exceptions import AriaCliError
 def reset(force, reset_config, logger):
     """
     Reset ARIA working directory
-    Resetting the working directory will result in the deletion of all state in ARIA; The user
-     configuration will remain intact, unless the `reset_config` flag has been set as well, in
-     which case the entire ARIA working directory shall be removed.
+
+    Deletes installed plugins, service templates, services, executions, and logs. The user
+    configuration will remain intact unless the `--reset_config` flag has been set as well, in
+    which case the entire ARIA working directory shall be removed.
     """
     if not force:
         raise AriaCliError("To reset the ARIA's working directory, you must also provide the force"

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/commands/service_templates.py
----------------------------------------------------------------------
diff --git a/aria/cli/commands/service_templates.py b/aria/cli/commands/service_templates.py
index d139195..f567aa8 100644
--- a/aria/cli/commands/service_templates.py
+++ b/aria/cli/commands/service_templates.py
@@ -13,6 +13,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+CLI ``service-templates`` sub-commands.
+"""
 
 import os
 
@@ -35,13 +38,14 @@ SERVICE_TEMPLATE_COLUMNS = \
 @aria.group(name='service-templates')
 @aria.options.verbose()
 def service_templates():
-    """Handle service templates on the manager
+    """
+    Manage service templates
     """
     pass
 
 
 @service_templates.command(name='show',
-                           short_help='Show service template information')
+                           short_help='Show information for a stored service template')
 @aria.argument('service-template-name')
 @aria.options.verbose()
 @aria.pass_model_storage
@@ -52,9 +56,10 @@ def service_templates():
 @aria.pass_logger
 def show(service_template_name, model_storage, mode_full, mode_types, format_json, format_yaml,
          logger):
-    """Show information for a specific service template
+    """
+    Show information for a stored service template
 
-    `SERVICE_TEMPLATE_NAME` is the name of the service template to show information on.
+    SERVICE_TEMPLATE_NAME is the unique name of the stored service template.
     """
     service_template = model_storage.service_template.get_by_name(service_template_name)
 
@@ -94,14 +99,15 @@ def show(service_template_name, model_storage, mode_full, mode_types, format_jso
 
 
 @service_templates.command(name='list',
-                           short_help='List service templates')
+                           short_help='List all stored service templates')
 @aria.options.sort_by()
 @aria.options.descending
 @aria.options.verbose()
 @aria.pass_model_storage
 @aria.pass_logger
 def list(sort_by, descending, model_storage, logger):
-    """List all service templates
+    """
+    List all stored service templates
     """
 
     logger.info('Listing all service templates...')
@@ -115,7 +121,7 @@ def list(sort_by, descending, model_storage, logger):
 
 
 @service_templates.command(name='store',
-                           short_help='Store a service template')
+                           short_help='Parse and store a service template archive')
 @aria.argument('service-template-path')
 @aria.argument('service-template-name')
 @aria.options.service_template_filename
@@ -126,11 +132,12 @@ def list(sort_by, descending, model_storage, logger):
 @aria.pass_logger
 def store(service_template_path, service_template_name, service_template_filename,
           model_storage, resource_storage, plugin_manager, logger):
-    """Store a service template
+    """
+    Parse and store a service template archive
 
-    `SERVICE_TEMPLATE_PATH` is the path of the service template to store.
+    SERVICE_TEMPLATE_PATH is the path to the service template archive.
 
-    `SERVICE_TEMPLATE_NAME` is the name of the service template to store.
+    SERVICE_TEMPLATE_NAME is the unique name to give to the service template in storage.
     """
     logger.info('Storing service template {0}...'.format(service_template_name))
 
@@ -148,7 +155,7 @@ def store(service_template_path, service_template_name, service_template_filenam
 
 
 @service_templates.command(name='delete',
-                           short_help='Delete a service template')
+                           short_help='Delete a stored service template')
 @aria.argument('service-template-name')
 @aria.options.verbose()
 @aria.pass_model_storage
@@ -156,9 +163,10 @@ def store(service_template_path, service_template_name, service_template_filenam
 @aria.pass_plugin_manager
 @aria.pass_logger
 def delete(service_template_name, model_storage, resource_storage, plugin_manager, logger):
-    """Delete a service template
+    """
+    Delete a stored service template
 
-    `SERVICE_TEMPLATE_NAME` is the name of the service template to delete.
+    SERVICE_TEMPLATE_NAME is the unique name of the stored service template.
     """
     logger.info('Deleting service template {0}...'.format(service_template_name))
     service_template = model_storage.service_template.get_by_name(service_template_name)
@@ -168,22 +176,23 @@ def delete(service_template_name, model_storage, resource_storage, plugin_manage
 
 
 @service_templates.command(name='inputs',
-                           short_help='Show service template inputs')
+                           short_help='Show stored service template inputs')
 @aria.argument('service-template-name')
 @aria.options.verbose()
 @aria.pass_model_storage
 @aria.pass_logger
 def inputs(service_template_name, model_storage, logger):
-    """Show inputs for a specific service template
+    """
+    Show stored service template inputs
 
-    `SERVICE_TEMPLATE_NAME` is the name of the service template to show inputs for.
+    SERVICE_TEMPLATE_NAME is the unique name of the stored service template.
     """
     logger.info('Showing inputs for service template {0}...'.format(service_template_name))
     print_service_template_inputs(model_storage, service_template_name, logger)
 
 
 @service_templates.command(name='validate',
-                           short_help='Validate a service template')
+                           short_help='Validate a service template archive')
 @aria.argument('service-template')
 @aria.options.service_template_filename
 @aria.options.verbose()
@@ -193,9 +202,10 @@ def inputs(service_template_name, model_storage, logger):
 @aria.pass_logger
 def validate(service_template, service_template_filename,
              model_storage, resource_storage, plugin_manager, logger):
-    """Validate a service template
+    """
+    Validate a service template archive
 
-    `SERVICE_TEMPLATE` is the path or URL of the service template or archive to validate.
+    SERVICE_TEMPLATE_PATH is the path to the service template archive.
     """
     logger.info('Validating service template: {0}'.format(service_template))
     service_template_path = service_template_utils.get(service_template, service_template_filename)
@@ -205,16 +215,18 @@ def validate(service_template, service_template_filename,
 
 
 @service_templates.command(name='create-archive',
-                           short_help='Create a CSAR archive')
+                           short_help='Create a CSAR archive from a service template source')
 @aria.argument('service-template-path')
 @aria.argument('destination')
 @aria.options.verbose()
 @aria.pass_logger
 def create_archive(service_template_path, destination, logger):
-    """Create a CSAR archive
+    """
+    Create a CSAR archive from a service template source
+
+    SERVICE_TEMPLATE_PATH is the path to the service template source.
 
-    `service_template_path` is the path of the service template to create the archive from
-    `destination` is the path of the output CSAR archive
+    DESTINATION is the path to the created CSAR archive.
     """
     logger.info('Creating a CSAR archive')
     if not destination.endswith(csar.CSAR_FILE_EXTENSION):

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/commands/services.py
----------------------------------------------------------------------
diff --git a/aria/cli/commands/services.py b/aria/cli/commands/services.py
index ae5895a..a99f5b3 100644
--- a/aria/cli/commands/services.py
+++ b/aria/cli/commands/services.py
@@ -13,6 +13,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+CLI ``services`` sub-commands.
+"""
 
 import os
 from StringIO import StringIO
@@ -36,13 +39,14 @@ SERVICE_COLUMNS = ('id', 'name', 'description', 'service_template_name', 'create
 @aria.group(name='services')
 @aria.options.verbose()
 def services():
-    """Handle services
+    """
+    Manage services
     """
     pass
 
 
 @services.command(name='show',
-                  short_help='Display service information')
+                  short_help='Show information for a service')
 @aria.argument('service-name')
 @aria.options.verbose()
 @aria.options.service_mode_full
@@ -52,9 +56,10 @@ def services():
 @aria.pass_model_storage
 @aria.pass_logger
 def show(service_name, model_storage, mode_full, mode_graph, format_json, format_yaml, logger):
-    """Show information for a specific service template
+    """
+    Show information for a service
 
-    `SERVICE_NAME` is the name of the service to display information on.
+    SERVICE_NAME is the unique name of the service.
     """
     service = model_storage.service.get_by_name(service_name)
 
@@ -99,10 +104,11 @@ def list(service_template_name,
          descending,
          model_storage,
          logger):
-    """List services
+    """
+    List services
 
-    If `--service-template-name` is provided, list services for that service template.
-    Otherwise, list services for all service templates.
+    If `--service-template-name` is provided, list services based on that service template.
+    Otherwise, list all services.
     """
     if service_template_name:
         logger.info('Listing services for service template {0}...'.format(
@@ -120,7 +126,7 @@ def list(service_template_name,
 
 
 @services.command(name='create',
-                  short_help='Create a services')
+                  short_help='Create a service')
 @aria.argument('service-name', required=False)
 @aria.options.service_template_name(required=True)
 @aria.options.inputs(help=helptexts.SERVICE_INPUTS)
@@ -136,10 +142,10 @@ def create(service_template_name,
            resource_storage,
            plugin_manager,
            logger):
-    """Create a service
-
-    `SERVICE_NAME` is the name of the service you'd like to create.
+    """
+    Create a service
 
+    SERVICE_NAME is the unique name to give to the service.
     """
     logger.info('Creating new service from service template {0}...'.format(
         service_template_name))
@@ -168,9 +174,10 @@ def create(service_template_name,
 @aria.pass_plugin_manager
 @aria.pass_logger
 def delete(service_name, force, model_storage, resource_storage, plugin_manager, logger):
-    """Delete a service
+    """
+    Delete a service
 
-    `SERVICE_NAME` is the name of the service to delete.
+    SERVICE_NAME is the unique name of the service.
     """
     logger.info('Deleting service {0}...'.format(service_name))
     service = model_storage.service.get_by_name(service_name)
@@ -186,9 +193,10 @@ def delete(service_name, force, model_storage, resource_storage, plugin_manager,
 @aria.pass_model_storage
 @aria.pass_logger
 def outputs(service_name, model_storage, logger):
-    """Show outputs for a specific service
+    """
+    Show service outputs
 
-    `SERVICE_NAME` is the name of the service to print outputs for.
+    SERVICE_NAME is the unique name of the service.
     """
     logger.info('Showing outputs for service {0}...'.format(service_name))
     service = model_storage.service.get_by_name(service_name)
@@ -211,9 +219,10 @@ def outputs(service_name, model_storage, logger):
 @aria.pass_model_storage
 @aria.pass_logger
 def inputs(service_name, model_storage, logger):
-    """Show inputs for a specific service
+    """
+    Show service inputs
 
-    `SERVICE_NAME` is the id of the service to print inputs for.
+    SERVICE_NAME is the unique name of the service.
     """
     logger.info('Showing inputs for service {0}...'.format(service_name))
     service = model_storage.service.get_by_name(service_name)

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/commands/workflows.py
----------------------------------------------------------------------
diff --git a/aria/cli/commands/workflows.py b/aria/cli/commands/workflows.py
index 221dbc4..03cf00e 100644
--- a/aria/cli/commands/workflows.py
+++ b/aria/cli/commands/workflows.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+CLI ``worfklows`` sub-commands.
+"""
+
 from .. import table
 from ..core import aria
 from ..exceptions import AriaCliError
@@ -22,22 +26,26 @@ WORKFLOW_COLUMNS = ['name', 'service_template_name', 'service_name']
 
 @aria.group(name='workflows')
 def workflows():
-    """Handle service workflows
+    """
+    Manage service workflows
     """
     pass
 
 
 @workflows.command(name='show',
-                   short_help='Show workflow information')
+                   short_help='Show information for a service workflow')
 @aria.argument('workflow-name')
 @aria.options.service_name(required=True)
 @aria.options.verbose()
 @aria.pass_model_storage
 @aria.pass_logger
 def show(workflow_name, service_name, model_storage, logger):
-    """Show information for a specific workflow of a specific service
+    """
+    Show information for a service workflow
 
-    `WORKFLOW_NAME` is the name of the workflow to get information on.
+    SERVICE_NAME is the unique name of the service.
+
+    WORKFLOW_NAME is the unique name of the workflow within the service (e.g. "uninstall").
     """
     logger.info('Retrieving workflow {0} for service {1}'.format(
         workflow_name, service_name))
@@ -81,13 +89,16 @@ def show(workflow_name, service_name, model_storage, logger):
 
 
 @workflows.command(name='list',
-                   short_help='List workflows for a service')
+                   short_help='List service workflows')
 @aria.options.service_name(required=True)
 @aria.options.verbose()
 @aria.pass_model_storage
 @aria.pass_logger
 def list(service_name, model_storage, logger):
-    """List all workflows of a specific service
+    """
+    List service workflows
+
+    SERVICE_NAME is the unique name of the service.
     """
     logger.info('Listing workflows for service {0}...'.format(service_name))
     service = model_storage.service.get_by_name(service_name)

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/config/__init__.py
----------------------------------------------------------------------
diff --git a/aria/cli/config/__init__.py b/aria/cli/config/__init__.py
index ae1e83e..738e8ed 100644
--- a/aria/cli/config/__init__.py
+++ b/aria/cli/config/__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.
+
+"""
+CLI configuration package.
+"""

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/config/config.py
----------------------------------------------------------------------
diff --git a/aria/cli/config/config.py b/aria/cli/config/config.py
index d584fad..bbece80 100644
--- a/aria/cli/config/config.py
+++ b/aria/cli/config/config.py
@@ -13,6 +13,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+CLI configuration mechanism.
+"""
 
 import os
 import pkg_resources

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/core/__init__.py
----------------------------------------------------------------------
diff --git a/aria/cli/core/__init__.py b/aria/cli/core/__init__.py
index ae1e83e..88a9801 100644
--- a/aria/cli/core/__init__.py
+++ b/aria/cli/core/__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.
+
+"""
+CLI core package.
+"""

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/core/aria.py
----------------------------------------------------------------------
diff --git a/aria/cli/core/aria.py b/aria/cli/core/aria.py
index e5b3eb2..515c06a 100644
--- a/aria/cli/core/aria.py
+++ b/aria/cli/core/aria.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Enhancements and ARIA-specific conveniences for `Click <http://click.pocoo.org>`__.
+"""
+
 import os
 import sys
 import difflib
@@ -227,9 +231,8 @@ class AliasedGroup(click.Group):
 
     def resolve_command(self, ctx, args):
         """
-        Override clicks ``resolve_command`` method
-        and appends *Did you mean ...* suggestions
-        to the raised exception message.
+        Override clicks ``resolve_command`` method and appends *Did you mean ...* suggestions to the
+        raised exception message.
         """
         try:
             return super(AliasedGroup, self).resolve_command(ctx, args)
@@ -250,7 +253,7 @@ class AliasedGroup(click.Group):
 
 def group(name):
     """
-    Allow to create a group with a default click context and a cls for click's ``didyoueamn``
+    Allow to create a group with a default click context and a class for Click's ``didyoueamn``
     without having to repeat it for every group.
     """
     return click.group(
@@ -271,7 +274,7 @@ def command(*args, **kwargs):
 
 def argument(*args, **kwargs):
     """
-    Make Click arguments ARIA specific.
+    Make Click arguments specific to ARIA.
 
     This exists purely for aesthetic reasons, otherwise some decorators are called
     ``@click.something`` instead of ``@aria.something``

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/csar.py
----------------------------------------------------------------------
diff --git a/aria/cli/csar.py b/aria/cli/csar.py
index 8f44557..40b1699 100644
--- a/aria/cli/csar.py
+++ b/aria/cli/csar.py
@@ -13,6 +13,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Support for the CSAR (Cloud Service ARchive) packaging specification.
+
+See the `TOSCA Simple Profile v1.0 cos01 specification <http://docs.oasis-open.org/tosca
+/TOSCA-Simple-Profile-YAML/v1.0/cos01/TOSCA-Simple-Profile-YAML-v1.0-cos01.html#_Toc461787381>`__
+"""
+
 import os
 import logging
 import pprint

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/defaults.py
----------------------------------------------------------------------
diff --git a/aria/cli/defaults.py b/aria/cli/defaults.py
index 5c16938..e84abc0 100644
--- a/aria/cli/defaults.py
+++ b/aria/cli/defaults.py
@@ -13,8 +13,18 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Various CLI default values.
+"""
 
+#: Default service template filename
 SERVICE_TEMPLATE_FILENAME = 'service_template.yaml'
+
+#: Default task max attempts
 TASK_MAX_ATTEMPTS = 30
+
+#: Default task retry interval
 TASK_RETRY_INTERVAL = 30
+
+#: Default sort descending
 SORT_DESCENDING = False

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/env.py
----------------------------------------------------------------------
diff --git a/aria/cli/env.py b/aria/cli/env.py
index 52a4ec6..84bdebe 100644
--- a/aria/cli/env.py
+++ b/aria/cli/env.py
@@ -13,6 +13,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Environment (private)
+"""
 
 import os
 import shutil

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/exceptions.py
----------------------------------------------------------------------
diff --git a/aria/cli/exceptions.py b/aria/cli/exceptions.py
index 89cfacd..7da9836 100644
--- a/aria/cli/exceptions.py
+++ b/aria/cli/exceptions.py
@@ -13,6 +13,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+CLI exceptions.
+"""
 
 from ..exceptions import AriaError
 

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/execution_logging.py
----------------------------------------------------------------------
diff --git a/aria/cli/execution_logging.py b/aria/cli/execution_logging.py
index 248ff7c..af40e01 100644
--- a/aria/cli/execution_logging.py
+++ b/aria/cli/execution_logging.py
@@ -12,6 +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.
+
+"""
+Formatting for ``executions`` sub-commands.
+"""
+
 import os
 import re
 from StringIO import StringIO

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/helptexts.py
----------------------------------------------------------------------
diff --git a/aria/cli/helptexts.py b/aria/cli/helptexts.py
index 74934db..a5d41e8 100644
--- a/aria/cli/helptexts.py
+++ b/aria/cli/helptexts.py
@@ -13,10 +13,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Gathers all CLI command help texts in one place.
+"""
 
 DEFAULT_MUTUALITY_ERROR_MESSAGE = 'mutually exclusive'
 VERBOSE = \
-    "Show verbose output. You can supply this up to three times (i.e. -vvv)"
+    "Show verbose output; you can supply this up to three times (i.e. -vvv)"
 
 VERSION = "Display the version and exit"
 FORCE_RESET = "Confirmation for resetting ARIA's working directory"
@@ -28,12 +31,12 @@ EXECUTION_ID = "The unique identifier for the execution"
 
 SERVICE_TEMPLATE_PATH = "The path to the application's service template file"
 SERVICE_TEMPLATE_FILENAME = (
-    "The name of the archive's main service template file. "
-    "This is only relevant if uploading a (non-CSAR) archive")
+    "The name of the archive's main service template file "
+    "(only relevant if uploading a non-CSAR archive)")
 INPUTS_PARAMS_USAGE = (
-    '(Can be provided as wildcard based paths '
-    '(*.yaml, /my_inputs/, etc..) to YAML files, a JSON string or as '
-    'key1=value1;key2=value2). This argument can be used multiple times')
+    '(can be provided as wildcard based paths '
+    '("inp?.yaml", "/my_inputs/", etc.) to YAML files, a JSON string or as '
+    '"key1=value1;key2=value2"); this argument can be used multiple times')
 SERVICE_INPUTS = "Inputs for the service {0}".format(INPUTS_PARAMS_USAGE)
 EXECUTION_INPUTS = "Inputs for the execution {0}".format(INPUTS_PARAMS_USAGE)
 
@@ -46,8 +49,8 @@ DRY_EXECUTION = "Execute a workflow dry run (prints operations information witho
 IGNORE_AVAILABLE_NODES = "Delete the service even if it has available nodes"
 SORT_BY = "Key for sorting the list"
 DESCENDING = "Sort list in descending order [default: False]"
-JSON_OUTPUT = "Output logs in a consumable JSON format"
-MARK_PATTERN = "Mark a regex pattern in the logs"
+JSON_OUTPUT = "Output logs in JSON format"
+MARK_PATTERN = "Mark a regular expression pattern in the logs"
 
 SHOW_FULL = "Show full information"
 SHOW_JSON = "Show in JSON format (implies --full)"

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/inputs.py
----------------------------------------------------------------------
diff --git a/aria/cli/inputs.py b/aria/cli/inputs.py
index 4d46ebb..bea3e1a 100644
--- a/aria/cli/inputs.py
+++ b/aria/cli/inputs.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Helpers for validating and coercing service template inputs.
+"""
+
 import os
 import glob
 from ruamel import yaml
@@ -22,15 +26,17 @@ from .exceptions import AriaCliError
 
 
 def inputs_to_dict(resources):
-    """Returns a dictionary of inputs
-
-    `resources` can be:
-    - A list of files.
-    - A single file
-    - A directory containing multiple input files
-    - A key1=value1;key2=value2 pairs string.
-    - A string formatted as JSON/YAML.
-    - Wildcard based string (e.g. *-inputs.yaml)
+    """
+    Returns a dictionary of inputs
+
+    :param resources: can be:
+
+     * list of files
+     * single file
+     * directory containing multiple input files
+     * ``key1=value1;key2=value2`` pairs string.
+     * string formatted as JSON/YAML
+     * wildcard based string (e.g. ``*-inputs.yaml``)
     """
     if not resources:
         return dict()

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/logger.py
----------------------------------------------------------------------
diff --git a/aria/cli/logger.py b/aria/cli/logger.py
index 96f3fb3..14baae0 100644
--- a/aria/cli/logger.py
+++ b/aria/cli/logger.py
@@ -13,6 +13,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Centralized logging configuration and formatting.
+"""
 
 import os
 import copy

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/main.py
----------------------------------------------------------------------
diff --git a/aria/cli/main.py b/aria/cli/main.py
index 02cf095..640360b 100644
--- a/aria/cli/main.py
+++ b/aria/cli/main.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Executable entry point into the CLI.
+"""
+
 from aria import install_aria_extensions
 from aria.cli import commands
 from aria.cli.core import aria
@@ -22,12 +26,15 @@ from aria.cli.core import aria
 @aria.options.verbose()
 @aria.options.version
 def _aria():
-    """ARIA's Command Line Interface
+    """
+    ARIA's Command Line Interface.
+
+    To activate bash-completion run::
 
-    To activate bash-completion. Run: `eval "$(_ARIA_COMPLETE=source aria)"`
+        eval "$(_ARIA_COMPLETE=source aria)"
 
-    ARIA's working directory resides by default in ~/.aria. To change it, set
-    the environment variable `ARIA_WORKDIR` to something else (e.g. /tmp/).
+    ARIA's working directory resides by default in "~/.aria". To change it, set the environment
+    variable ARIA_WORKDIR to something else (e.g. "/tmp/").
     """
     aria.set_cli_except_hook()
 

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/service_template_utils.py
----------------------------------------------------------------------
diff --git a/aria/cli/service_template_utils.py b/aria/cli/service_template_utils.py
index c953c02..5312522 100644
--- a/aria/cli/service_template_utils.py
+++ b/aria/cli/service_template_utils.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Loading mechanism for service templates.
+"""
+
 import os
 from urlparse import urlparse
 
@@ -23,26 +27,24 @@ from ..utils import archive as archive_utils
 
 
 def get(source, service_template_filename):
-    """Get a source and return a path to the main service template file
+    """
+    Get a source and return a path to the main service template file
 
     The behavior based on then source argument content is:
-        - local yaml file: return the file
-        - local archive:
-            extract it locally and return path service template file
-        - URL:
-            - download and get service template from downloaded archive
-        - github repo:
-            - download and get service template from downloaded archive
-
-    Supported archive types are: csar, zip, tar, tar.gz and tar.bz2
-
-    :param source: Path/URL/github repo to archive/service-template file
-    :type source: str
-    :param service_template_filename: Path to service template (if source is an archive [but
-     not a csar archive - with csars archives, this is read from the metadata file])
-    :type service_template_filename: str
-    :return: Path to main service template file
-    :rtype: str
+
+    * local ``.yaml`` file: return the file
+    * local archive (``.csar``, ``.zip``, ``.tar``, ``.tar.gz``, and ``.tar.bz2``): extract it
+      locally and return path service template file
+    * URL: download and get service template from downloaded archive
+    * GitHub repo: download and get service template from downloaded archive
+
+    :param source: path/URL/GitHub repo to archive/service-template file
+    :type source: basestring
+    :param service_template_filename: path to service template if source is a non-CSAR archive
+     with CSAR archives, this is read from the metadata file)
+    :type service_template_filename: basestring
+    :return: path to main service template file
+    :rtype: basestring
     """
     if urlparse(source).scheme:
         downloaded_file = utils.download_file(source)
@@ -66,14 +68,15 @@ def get(source, service_template_filename):
 
 
 def _get_service_template_file_from_archive(archive, service_template_filename):
-    """Extract archive to temporary location and get path to service template file.
+    """
+    Extract archive to temporary location and get path to service template file.
 
-    :param archive: Path to archive file
-    :type archive: str
-    :param service_template_filename: Path to service template file relative to archive
-    :type service_template_filename: str
-    :return: Absolute path to service template file
-    :rtype: str
+    :param archive: path to archive file
+    :type archive: basestring
+    :param service_template_filename: path to service template file relative to archive
+    :type service_template_filename: basestring
+    :return: absolute path to service template file
+    :rtype: basestring
 
     """
     if csar.is_csar_archive(archive):
@@ -95,12 +98,13 @@ def _get_service_template_file_from_archive(archive, service_template_filename):
 
 
 def _map_to_github_url(source):
-    """Returns a path to a downloaded github archive.
+    """
+    Returns a path to a downloaded GitHub archive.
 
-    :param source: github repo in the format of `org/repo[:tag/branch]`.
-    :type source: str
-    :return: URL to the archive file for the given repo in github
-    :rtype: str
+    :param source: GitHub repo: ``org/repo[:tag/branch]``
+    :type source: basestring
+    :return: URL to the archive file for the given repo in GitHub
+    :rtype: basestring
 
     """
     source_parts = source.split(':', 1)

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/table.py
----------------------------------------------------------------------
diff --git a/aria/cli/table.py b/aria/cli/table.py
index d984c87..74487ae 100644
--- a/aria/cli/table.py
+++ b/aria/cli/table.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Tabular formatting utilities.
+"""
+
 import os
 from datetime import datetime
 
@@ -23,6 +27,23 @@ from .env import logger
 
 def print_data(columns, items, header_text,
                column_formatters=None, col_max_width=None, defaults=None):
+    """
+    Prints data in a tabular form.
+
+    :param columns: columns of the table, e.g. ``['id','name']``
+    :type columns: iterable of basestring
+    :param items: each element must have keys or attributes corresponding to the ``columns`` items,
+     e.g. ``[{'id':'123', 'name':'Pete'}]``
+    :type data: [{:obj:`basestring`: :obj:`basestring`}]
+    :param column_formatters: maps column name to formatter, a function that may manipulate the
+     string values printed for this column, e.g. ``{'created_at': timestamp_formatter}``
+    :type column_formatters: {:obj:`basestring`: :obj:`function`}
+    :param col_max_width: maximum width of table
+    :type col_max_width: int
+    :param defaults: default values for keys that don't exist in the data itself, e.g.
+     ``{'serviceId':'123'}``
+    :type defaults: {:obj:`basestring`: :obj:`basestring`}
+    """
     if items is None:
         items = []
     elif not isinstance(items, list):
@@ -43,30 +64,17 @@ def _generate(cols, data, column_formatters=None, defaults=None):
     """
     Return a new PrettyTable instance representing the list.
 
-    Arguments:
-
-        cols - An iterable of strings that specify what
-               are the columns of the table.
-
-               for example: ['id','name']
-
-        data - An iterable of dictionaries or objects, each element must
-               have keys or attributes corresponding to the cols items.
-
-               for example: [{'id':'123', 'name':'Pete'}]
-
-        column_formatters - A dictionary from a column name to a formatter - a function that
-                            may manipulate the string values printed for this column.
-                            (See below for a few built-in formatter examples)
-
-                            for example: {'created_at': timestamp_formatter}
-
-        defaults - A dictionary specifying default values for
-                   key's that don't exist in the data itself.
-
-                   for example: {'serviceId':'123'} will set the
-                   serviceId value for all rows to '123'.
-
+    :param cols: columns of the table, e.g. ``['id','name']``
+    :type cols: iterable of :obj:`basestring`
+    :param data: each element must have keys or attributes corresponding to the ``cols`` items,
+     e.g. ``[{'id':'123', 'name':'Pete'}]``
+    :type data: [{:obj:`basestring`: :obj:`basestring`}]
+    :param column_formatters: maps column name to formatter, a function that may manipulate the
+     string values printed for this column, e.g. ``{'created_at': timestamp_formatter}``
+    :type column_formatters: {:obj:`basestring`: :obj:`function`}
+    :param defaults: default values for keys that don't exist in the data itself, e.g.
+     ``{'serviceId':'123'}``
+    :type defaults: {:obj:`basestring`: :obj:`basestring`}
     """
     def get_values_per_column(column, row_data):
         if hasattr(row_data, column) or (isinstance(row_data, dict) and column in row_data):

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/cli/utils.py
----------------------------------------------------------------------
diff --git a/aria/cli/utils.py b/aria/cli/utils.py
index 852f24d..697ff37 100644
--- a/aria/cli/utils.py
+++ b/aria/cli/utils.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Miscellaneous CLI utilities.
+"""
+
 import os
 import sys
 from StringIO import StringIO
@@ -44,8 +48,8 @@ def get_parameter_templates_as_string(parameter_templates):
 
 def check_overriding_storage_exceptions(e, model_class, name):
     """
-    This method checks whether the storage exception is a known type where we'd like to override
-     the exception message; If so, it raises a new error. Otherwise it simply returns.
+    Checks whether the storage exception is a known type where we'd like to override the exception
+    message; If so, it raises a new error. Otherwise it simply returns.
     """
     assert isinstance(e, BaseException)
     if 'UNIQUE constraint failed' in e.message:
@@ -68,15 +72,16 @@ def download_file(url):
 
 
 def generate_progress_handler(file_path, action='', max_bar_length=80):
-    """Returns a function that prints a progress bar in the terminal
+    """
+    Returns a function that prints a progress bar in the terminal.
 
-    :param file_path: The name of the file being transferred
-    :param action: Uploading/Downloading
-    :param max_bar_length: Maximum allowed length of the bar. Default: 80
-    :return: The configured print_progress function
+    :param file_path: the name of the file being transferred
+    :param action: uploading/downloading
+    :param max_bar_length: maximum allowed length of the bar
+    :return: configured ``print_progress`` function
     """
-    # We want to limit the maximum line length to 80, but allow for a smaller
-    # terminal size. We also include the action string, and some extra chars
+    # We want to limit the maximum line length to 80, but allow for a smaller terminal size. We also
+    # include the action string, and some extra chars
     terminal_width = get_terminal_size().columns
 
     # This takes care of the case where there is no terminal (e.g. unittest)
@@ -91,24 +96,21 @@ def generate_progress_handler(file_path, action='', max_bar_length=80):
     bar_length -= len(file_name)
 
     def print_progress(read_bytes, total_bytes):
-        """Print upload/download progress on a single line
+        """
+        Print upload/download progress on a single line.
 
-        Call this function in a loop to create a progress bar in the terminal
+        Call this function in a loop to create a progress bar in the terminal.
 
-        :param read_bytes: Number of bytes already processed
-        :param total_bytes: Total number of bytes in the file
+        :param read_bytes: number of bytes already processed
+        :param total_bytes: total number of bytes in the file
         """
 
-        filled_length = min(bar_length, int(round(bar_length * read_bytes /
-                                                  float(total_bytes))))
-        percents = min(100.00, round(
-            100.00 * (read_bytes / float(total_bytes)), 2))
+        filled_length = min(bar_length, int(round(bar_length * read_bytes / float(total_bytes))))
+        percents = min(100.00, round(100.00 * (read_bytes / float(total_bytes)), 2))
         bar = '#' * filled_length + '-' * (bar_length - filled_length)  # pylint: disable=blacklisted-name
 
-        # The \r caret makes sure the cursor moves back to the beginning of
-        # the line
-        sys.stdout.write('\r{0} {1} |{2}| {3}%'.format(
-            action, file_name, bar, percents))
+        # The \r caret makes sure the cursor moves back to the beginning of the line
+        sys.stdout.write('\r{0} {1} |{2}| {3}%'.format(action, file_name, bar, percents))
         if read_bytes >= total_bytes:
             sys.stdout.write(os.linesep)
 

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/core.py
----------------------------------------------------------------------
diff --git a/aria/core.py b/aria/core.py
index f660167..a8d5245 100644
--- a/aria/core.py
+++ b/aria/core.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+ARIA core module.
+"""
+
 from . import exceptions
 from .parser import consumption
 from .parser.loading.location import UriLocation

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/exceptions.py
----------------------------------------------------------------------
diff --git a/aria/exceptions.py b/aria/exceptions.py
index 93987dc..5d3e21d 100644
--- a/aria/exceptions.py
+++ b/aria/exceptions.py
@@ -14,9 +14,7 @@
 # limitations under the License.
 
 """
-ARIA exceptions module
-Every sub-package in ARIA has a module with its exceptions.
-aria.exceptions module conveniently collects all these exceptions for easier imports.
+Base exception classes and other common exceptions used throughout ARIA.
 """
 
 import sys
@@ -48,21 +46,21 @@ class AriaException(Exception):
 
 class DependentServicesError(AriaError):
     """
-    Raised when attempting to delete a service template which has existing services
+    Raised when attempting to delete a service template which has existing services.
     """
     pass
 
 
 class DependentActiveExecutionsError(AriaError):
     """
-    Raised when attempting to delete a service which has active executions
+    Raised when attempting to delete a service which has active executions.
     """
     pass
 
 
 class DependentAvailableNodesError(AriaError):
     """
-    Raised when attempting to delete a service which has available nodes
+    Raised when attempting to delete a service which has available nodes.
     """
     pass
 

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/extension.py
----------------------------------------------------------------------
diff --git a/aria/extension.py b/aria/extension.py
index 4dba74f..e90750d 100644
--- a/aria/extension.py
+++ b/aria/extension.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Mechanism for registering and loading ARIA extensions.
+"""
+
 # pylint: disable=no-self-use
 
 from .utils import collections
@@ -49,7 +53,9 @@ def _registrar(function):
 
 
 class _ExtensionRegistration(object):
-    """Base class for extension class decorators"""
+    """
+    Base class for extension class decorators.
+    """
 
     def __init__(self):
         self._registrars = {}
@@ -70,7 +76,7 @@ class _ExtensionRegistration(object):
 
     def init(self):
         """
-        Initialize all registrars by calling all registered functions
+        Initialize all registrars by calling all registered functions.
         """
         registered_instances = [cls() for cls in self._registered_classes]
         for name, registrar in self._registrars.items():
@@ -81,13 +87,16 @@ class _ExtensionRegistration(object):
 
 
 class _ParserExtensionRegistration(_ExtensionRegistration):
-    """Parser extensions class decorator"""
+    """
+    Parser extensions class decorator.
+    """
 
     @_registrar
     def presenter_class(self):
         """
         Presentation class registration.
-        Implementing functions can return a single class or a list/tuple of classes
+
+        Implementing functions can return a single class or a list/tuple of classes.
         """
         return []
 
@@ -95,7 +104,8 @@ class _ParserExtensionRegistration(_ExtensionRegistration):
     def specification_package(self):
         """
         Specification package registration.
-        Implementing functions can return a package name or a list/tuple of names
+
+        Implementing functions can return a package name or a list/tuple of names.
         """
         return []
 
@@ -103,7 +113,8 @@ class _ParserExtensionRegistration(_ExtensionRegistration):
     def specification_url(self):
         """
         Specification URL registration.
-        Implementing functions should return a dictionary from names to URLs
+
+        Implementing functions should return a dictionary from names to URLs.
         """
         return {}
 
@@ -111,7 +122,8 @@ class _ParserExtensionRegistration(_ExtensionRegistration):
     def uri_loader_prefix(self):
         """
         URI loader prefix registration.
-        Implementing functions can return a single prefix or a list/tuple of prefixes
+
+        Implementing functions can return a single prefix or a list/tuple of prefixes.
         """
         return collections.StrictList(value_class=basestring)
 
@@ -119,13 +131,15 @@ parser = _ParserExtensionRegistration()
 
 
 class _ProcessExecutorExtensionRegistration(_ExtensionRegistration):
-    """Process executor extension class decorator"""
+    """
+    Process executor extension class decorator.
+    """
 
     @_registrar
     def decorate(self):
         """
         The operation function executed by the process executor will be decorated with the function
-        returned from decorate().
+        returned from ``decorate()``.
         """
         return []
 
@@ -134,7 +148,7 @@ process_executor = _ProcessExecutorExtensionRegistration()
 
 def init():
     """
-    Initialize all registrars by calling all registered functions
+    Initialize all registrars by calling all registered functions.
     """
     parser.init()
     process_executor.init()

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/logger.py
----------------------------------------------------------------------
diff --git a/aria/logger.py b/aria/logger.py
index bd7ed4e..f4f6ec9 100644
--- a/aria/logger.py
+++ b/aria/logger.py
@@ -14,7 +14,8 @@
 # limitations under the License.
 
 """
-Logging related mixins and functions
+Mix-ins and functions for logging, supporting multiple backends (such as SQL) and consistent
+formatting.
 """
 
 import logging
@@ -38,12 +39,11 @@ _base_logger = logging.getLogger('aria')
 
 class LoggerMixin(object):
     """
-    Mixin Logger Class
-    configuration (class members):
-        logger_name: logger name [default: <class_name>]
-        logger_level: logger level [default: logging.DEBUG]
-        base_logger: This Mixing will create child logger from this base_logger
-                    [default: root logger]
+    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 base_logger: child loggers are created from this; defaults to the root logger
     """
     logger_name = None
     logger_level = logging.DEBUG
@@ -66,7 +66,7 @@ class LoggerMixin(object):
             base_logger=logging.getLogger(),
             **kwargs):
         """
-        Set the logger used by the consuming class
+        Set the logger used by the consuming class.
         """
         cls.logger_name = logger_name
         cls.logger_level = logger_level
@@ -86,10 +86,12 @@ class LoggerMixin(object):
 
 def create_logger(logger=_base_logger, handlers=(), **configs):
     """
-
-    :param logging.Logger logger: The logger name [default: aria logger]
-    :param list handlers: The logger handlers
-    :param configs: The logger configurations
+    :param logger: logger name; defaults to ARIA logger
+    :type logger: logging.Logger
+    :param handlers: logger handlers
+    :type handlers: []
+    :param configs: logger configurations
+    :type configs: []
     :return: logger
     """
     logger.handlers = []
@@ -103,10 +105,8 @@ def create_logger(logger=_base_logger, handlers=(), **configs):
 
 def create_console_log_handler(level=logging.DEBUG, formatter=None):
     """
-
     :param level:
     :param formatter:
-    :return:
     """
     console = logging.StreamHandler()
     console.setLevel(level)
@@ -123,10 +123,9 @@ def create_sqla_log_handler(model, log_cls, execution_id, level=logging.DEBUG):
 
 class _DefaultConsoleFormat(logging.Formatter):
     """
-    _DefaultConsoleFormat class
-    Console logger formatter
-     info level logs format: '%(message)s'
-     every other log level are formatted: '%(levelname)s: %(message)s'
+    Info level log format: ``%(message)s``.
+
+    Every other log level is formatted: ``%(levelname)s: %(message)s``.
     """
     def format(self, record):
         try:
@@ -147,7 +146,7 @@ def create_file_log_handler(
         backup_count=10,
         formatter=None):
     """
-    Create a logging.handlers.RotatingFileHandler
+    Create a :class:`logging.handlers.RotatingFileHandler`.
     """
     rotating_file = logging_handlers.RotatingFileHandler(
         filename=file_path,
@@ -161,7 +160,6 @@ def create_file_log_handler(
 
 
 class _SQLAlchemyHandler(logging.Handler):
-
     def __init__(self, model, log_cls, execution_id, **kwargs):
         logging.Handler.__init__(self, **kwargs)
         self._model = model

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/modeling/__init__.py
----------------------------------------------------------------------
diff --git a/aria/modeling/__init__.py b/aria/modeling/__init__.py
index 4ac79e7..57bc188 100644
--- a/aria/modeling/__init__.py
+++ b/aria/modeling/__init__.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+This package provides an API for modeling ARIA's state and serializing it to storage.
+"""
+
 from collections import namedtuple
 
 from . import (

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/modeling/constraints.py
----------------------------------------------------------------------
diff --git a/aria/modeling/constraints.py b/aria/modeling/constraints.py
index 107b010..8ed33d5 100644
--- a/aria/modeling/constraints.py
+++ b/aria/modeling/constraints.py
@@ -13,6 +13,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Constraints for the requirements-and-capabilities matching mechanism.
+"""
 
 class NodeTemplateConstraint(object):
     """
@@ -23,6 +26,6 @@ class NodeTemplateConstraint(object):
 
     def matches(self, source_node_template, target_node_template):
         """
-        Returns true is the target matches the constraint for the source.
+        Returns ``True`` if the target matches the constraint for the source.
         """
         raise NotImplementedError

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/modeling/exceptions.py
----------------------------------------------------------------------
diff --git a/aria/modeling/exceptions.py b/aria/modeling/exceptions.py
index d0e3e22..573efaf 100644
--- a/aria/modeling/exceptions.py
+++ b/aria/modeling/exceptions.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Modeling exceptions.
+"""
+
 from ..exceptions import AriaException
 
 

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/modeling/functions.py
----------------------------------------------------------------------
diff --git a/aria/modeling/functions.py b/aria/modeling/functions.py
index 06fd19f..6544adf 100644
--- a/aria/modeling/functions.py
+++ b/aria/modeling/functions.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Mechanism for evaluating intrinsic functions.
+"""
+
 from ..parser.consumption import ConsumptionContext
 from ..parser.exceptions import InvalidValueError
 from ..utils.collections import OrderedDict
@@ -34,10 +38,11 @@ class Function(object):
 
     def __evaluate__(self, container_holder):
         """
-        Evaluates the function if possible. If impossible, raises
-        :class:`CannotEvaluateFunctionException` (do not just return None).
+        Evaluates the function if possible.
 
-        :rtype: Evaluation (or any object with ``value`` and ``final`` properties)
+        :rtype: :class:`Evaluation` (or any object with ``value`` and ``final`` properties)
+        :raises CannotEvaluateFunctionException: if cannot be evaluated at this time (do *not* just
+         return ``None``)
         """
 
         raise NotImplementedError
@@ -50,6 +55,10 @@ class Function(object):
 class Evaluation(object):
     """
     An evaluated :class:`Function` return value.
+
+    :ivar value: evaluated value
+    :ivar final: whether the value is final
+    :vartype final: boolean
     """
 
     def __init__(self, value, final=False):
@@ -60,13 +69,13 @@ class Evaluation(object):
 def evaluate(value, container_holder, report_issues=False): # pylint: disable=too-many-branches
     """
     Recursively attempts to call ``__evaluate__``. If an evaluation occurred will return an
-    :class:`Evaluation`, otherwise it will be None. If any evaluation is non-final, then the entire
-    evaluation will also be non-final.
+    :class:`Evaluation`, otherwise it will be ``None``. If any evaluation is non-final, then the
+    entire evaluation will also be non-final.
 
     The ``container_holder`` argument should have three properties: ``container`` should return
     the model that contains the value, ``service`` should return the containing
-    :class:`aria.modeling.models.Service` model or None, and ``service_template`` should return the
-    containing :class:`aria.modeling.models.ServiceTemplate` model or None.
+    :class:`~aria.modeling.models.Service` model or None, and ``service_template`` should return the
+    containing :class:`~aria.modeling.models.ServiceTemplate` model or ``None``.
     """
 
     evaluated = False


Mime
View raw message