ariatosca-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From r..@apache.org
Subject [3/8] incubator-ariatosca git commit: ARIA-286 Sphinx documentation for code and CLI
Date Thu, 29 Jun 2017 12:57:33 GMT
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/parser/presentation/fields.py
----------------------------------------------------------------------
diff --git a/aria/parser/presentation/fields.py b/aria/parser/presentation/fields.py
index 7f85723..959bad1 100644
--- a/aria/parser/presentation/fields.py
+++ b/aria/parser/presentation/fields.py
@@ -39,19 +39,16 @@ def has_fields(cls):
     """
     Class decorator for validated field support.
 
-    1. Adds a :code:`FIELDS` class property that is a dict of all the fields.
-       Will inherit and merge :code:`FIELDS` properties from base classes if
-       they have them.
+    1. Adds a ``FIELDS`` class property that is a dict of all the fields. Will inherit and merge
+       ``FIELDS`` properties from base classes if they have them.
 
-    2. Generates automatic :code:`@property` implementations for the fields
-       with the help of a set of special function decorators.
+    2. Generates automatic ``@property`` implementations for the fields with the help of a set of
+       special function decorators.
 
-    The class also works with the Python dict protocol, so that
-    fields can be accessed via dict semantics. The functionality is
-    identical to that of using attribute access.
+    The class also works with the Python dict protocol, so that fields can be accessed via dict
+    semantics. The functionality is identical to that of using attribute access.
 
-    The class will also gain two utility methods, :code:`_iter_field_names`
-    and :code:`_iter_fields`.
+    The class will also gain two utility methods, ``_iter_field_names`` and ``_iter_fields``.
     """
 
     # Make sure we have FIELDS
@@ -267,8 +264,8 @@ def field_getter(getter_func):
     """
     Method decorator for overriding the getter function of a field.
 
-    The signature of the getter function must be: :code:`f(field, presentation, context)`.
-    The default getter can be accessed as :code:`field.default_get(presentation, context)`.
+    The signature of the getter function must be: ``f(field, presentation, context)``.
+    The default getter can be accessed as ```field.default_get(presentation, context)``.
 
     The function must already be decorated with a field decorator.
     """
@@ -286,8 +283,8 @@ def field_setter(setter_func):
     """
     Method decorator for overriding the setter function of a field.
 
-    The signature of the setter function must be: :code:`f(field, presentation, context, value)`.
-    The default setter can be accessed as :code:`field.default_set(presentation, context, value)`.
+    The signature of the setter function must be: ``f(field, presentation, context, value)``.
+    The default setter can be accessed as ``field.default_set(presentation, context, value)``.
 
     The function must already be decorated with a field decorator.
     """
@@ -305,8 +302,8 @@ def field_validator(validator_fn):
     """
     Method decorator for overriding the validator function of a field.
 
-    The signature of the validator function must be: :code:f(field, presentation, context)`.
-    The default validator can be accessed as :code:`field.default_validate(presentation, context)`.
+    The signature of the validator function must be: ``f(field, presentation, context)``.
+    The default validator can be accessed as ``field.default_validate(presentation, context)``.
 
     The function must already be decorated with a field decorator.
     """
@@ -373,7 +370,7 @@ def has_fields_contains(self, key):
 
 class Field(object):
     """
-    Field handler used by :code:`@has_fields` decorator.
+    Field handler used by ``@has_fields`` decorator.
     """
 
     def __init__(self, field_variant, func, cls=None, default=None, allowed=None, required=False):

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/parser/presentation/null.py
----------------------------------------------------------------------
diff --git a/aria/parser/presentation/null.py b/aria/parser/presentation/null.py
index a018df4..287d2ba 100644
--- a/aria/parser/presentation/null.py
+++ b/aria/parser/presentation/null.py
@@ -33,7 +33,7 @@ NULL = Null()
 
 def none_to_null(value):
     """
-    Convert :code:`None` to :code:`NULL`, recursively.
+    Convert ``None`` to ``NULL``, recursively.
     """
 
     if value is None:
@@ -51,7 +51,7 @@ def none_to_null(value):
 
 def null_to_none(value):
     """
-    Convert :code:`NULL` to :code:`None`, recursively.
+    Convert ``NULL`` to ``None``, recursively.
     """
 
     if value is NULL:

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/parser/presentation/presentation.py
----------------------------------------------------------------------
diff --git a/aria/parser/presentation/presentation.py b/aria/parser/presentation/presentation.py
index 644d880..7292562 100644
--- a/aria/parser/presentation/presentation.py
+++ b/aria/parser/presentation/presentation.py
@@ -52,18 +52,17 @@ class PresentationBase(HasCachedMethods):
 
     def _validate(self, context):
         """
-        Validates the presentation while reporting errors in the validation context but
-        *not* raising exceptions.
+        Validates the presentation while reporting errors in the validation context but *not*
+        raising exceptions.
 
-        The base class does not thing, but subclasses may override this for specialized
-        validation.
+        The base class does not thing, but subclasses may override this for specialized validation.
         """
 
     @property
     def _fullname(self):
         """
-        Always returns a usable full name of the presentation, whether it itself is named,
-        or recursing to its container, and finally defaulting to the class name.
+        Always returns a usable full name of the presentation, whether it itself is named, or
+        recursing to its container, and finally defaulting to the class name.
         """
 
         if self._name is not None:
@@ -75,10 +74,10 @@ class PresentationBase(HasCachedMethods):
     @property
     def _locator(self):
         """
-        Attempts to return the most relevant locator, whether we have one, or recursing
-        to our container.
+        Attempts to return the most relevant locator, whether we have one, or recursing to our
+        container.
 
-        :rtype: :class:`aria.reading.Locator`
+        :rtype: :class:`aria.parser.reading.Locator`
         """
 
         return get_locator(self._raw, self._container)
@@ -98,8 +97,8 @@ class PresentationBase(HasCachedMethods):
 
     def _get_from_dict(self, *names):
         """
-        Gets attributes recursively, except for the last name which is used
-        to get a value from the last dict.
+        Gets attributes recursively, except for the last name which is used to get a value from the
+        last dict.
         """
 
         if names:
@@ -110,10 +109,10 @@ class PresentationBase(HasCachedMethods):
 
     def _get_child_locator(self, *names):
         """
-        Attempts to return the locator of one our children. Will default to our locator
-        if not found.
+        Attempts to return the locator of one our children. Will default to our locator if not
+        found.
 
-        :rtype: :class:`aria.reading.Locator`
+        :rtype: :class:`aria.parser.reading.Locator`
         """
 
         if hasattr(self._raw, '_locator'):
@@ -126,9 +125,8 @@ class PresentationBase(HasCachedMethods):
         """
         Emits a colorized representation.
 
-        The base class will emit a sensible default representation of the fields,
-        (by calling :code:`_dump_content`), but subclasses may override this for specialized
-        dumping.
+        The base class will emit a sensible default representation of the fields, (by calling
+        ``_dump_content``), but subclasses may override this for specialized dumping.
         """
 
         if self._name:
@@ -142,8 +140,8 @@ class PresentationBase(HasCachedMethods):
         """
         Emits a colorized representation of the contents.
 
-        The base class will call :code:`_dump_field` on all the fields, but subclasses may
-        override this for specialized dumping.
+        The base class will call ``_dump_field`` on all the fields, but subclasses may override
+        this for specialized dumping.
         """
 
         if field_names:
@@ -159,8 +157,8 @@ class PresentationBase(HasCachedMethods):
         """
         Emits a colorized representation of the field.
 
-        According to the field type, this may trigger nested recursion. The nested
-        types will delegate to their :code:`_dump` methods.
+        According to the field type, this may trigger nested recursion. The nested types will
+        delegate to their ``_dump`` methods.
         """
 
         field = self.FIELDS[field_name]  # pylint: disable=no-member
@@ -179,16 +177,14 @@ class PresentationBase(HasCachedMethods):
 
 class Presentation(PresentationBase):
     """
-    Base class for ARIA presentations. A presentation is a Pythonic wrapper around
-    agnostic raw data, adding the ability to read and modify the data with proper
-    validation.
+    Base class for ARIA presentations. A presentation is a Pythonic wrapper around agnostic raw
+    data, adding the ability to read and modify the data with proper validation.
 
-    ARIA presentation classes will often be decorated with @has_fields, as that
-    mechanism automates a lot of field-specific validation. However, that is not a
-    requirement.
+    ARIA presentation classes will often be decorated with :func:`has_fields`, as that mechanism
+    automates a lot of field-specific validation. However, that is not a requirement.
 
-    Make sure that your utility property and method names begin with a "_", because
-    those names without a "_" prefix are normally reserved for fields.
+    Make sure that your utility property and method names begin with a ``_``, because those names
+    without a ``_`` prefix are normally reserved for fields.
     """
 
     def _validate(self, context):

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/parser/presentation/source.py
----------------------------------------------------------------------
diff --git a/aria/parser/presentation/source.py b/aria/parser/presentation/source.py
index 7198b07..4bfb8e1 100644
--- a/aria/parser/presentation/source.py
+++ b/aria/parser/presentation/source.py
@@ -32,7 +32,7 @@ class PresenterSource(object):
 
 class DefaultPresenterSource(PresenterSource):
     """
-    The default ARIA presenter source supports TOSCA Simple Profile.
+    The default ARIA presenter source.
     """
 
     def __init__(self, classes=None):

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/parser/presentation/utils.py
----------------------------------------------------------------------
diff --git a/aria/parser/presentation/utils.py b/aria/parser/presentation/utils.py
index fbe971b..f0fd390 100644
--- a/aria/parser/presentation/utils.py
+++ b/aria/parser/presentation/utils.py
@@ -25,7 +25,7 @@ def get_locator(*values):
     """
     Gets the first available locator.
 
-    :rtype: :class:`aria.reading.Locator`
+    :rtype: :class:`aria.parser.reading.Locator`
     """
 
     for v in values:
@@ -53,7 +53,7 @@ def validate_primitive(value, cls, coerce=False):
     Checks if the value is of the primitive type, optionally attempting to coerce it
     if it is not.
 
-    Raises a :code:`ValueError` if it isn't or if coercion failed.
+    :raises ValueError: if not a primitive type or if coercion failed.
     """
 
     if (cls is not None) and (value is not None) and (value is not NULL):
@@ -112,14 +112,14 @@ def validate_known_fields(context, presentation):
 
 def get_parent_presentation(context, presentation, *types_dict_names):
     """
-    Returns the parent presentation according to the :code:`derived_from` field, or None if invalid.
+    Returns the parent presentation according to the ``derived_from`` field, or ``None`` if invalid.
 
     Checks that we do not derive from ourselves and that we do not cause a circular hierarchy.
 
     The arguments from the third onwards are used to locate a nested field under
-    :code:`service_template` under the root presenter. The first of these can optionally
-    be a function, in which case it will be called to convert type names. This can be used
-    to support shorthand type names, aliases, etc.
+    ``service_template`` under the root presenter. The first of these can optionally be a function,
+    in which case it will be called to convert type names. This can be used to support shorthand
+    type names, aliases, etc.
     """
 
     type_name = presentation.derived_from

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/parser/reading/__init__.py
----------------------------------------------------------------------
diff --git a/aria/parser/reading/__init__.py b/aria/parser/reading/__init__.py
index b5c0709..065ca56 100644
--- a/aria/parser/reading/__init__.py
+++ b/aria/parser/reading/__init__.py
@@ -10,6 +10,29 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Reading package.
+
+.. autosummary::
+   :nosignatures:
+
+   aria.parser.reading.ReadingContext
+   ReaderException
+   ReaderNotFoundError
+   ReaderSyntaxError
+   AlreadyReadException
+   JinjaReader
+   JsonReader
+   Locator
+   deepcopy_with_locators
+   copy_locators
+   RawReader
+   Reader
+   ReaderSource
+   DefaultReaderSource
+   YamlReader
+"""
+
 from .raw import RawReader
 from .reader import Reader
 from .yaml import YamlReader

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/parser/reading/context.py
----------------------------------------------------------------------
diff --git a/aria/parser/reading/context.py b/aria/parser/reading/context.py
index 02d4de9..233e407 100644
--- a/aria/parser/reading/context.py
+++ b/aria/parser/reading/context.py
@@ -16,10 +16,12 @@ from .source import DefaultReaderSource
 
 class ReadingContext(object):
     """
-    Properties:
+    Reading context.
 
-    * :code:`reader_source`: For finding reader instances
-    * :code:`reader`: Overrides :code:`reader_source` with a specific class
+    :ivar reader_source: for finding reader instances
+    :vartype reader_source: ReaderSource
+    :ivar reader: overrides ``reader_source`` with a specific class
+    :vartype reader: type
     """
 
     def __init__(self):

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/parser/reading/locator.py
----------------------------------------------------------------------
diff --git a/aria/parser/reading/locator.py b/aria/parser/reading/locator.py
index 4142ee7..965164d 100644
--- a/aria/parser/reading/locator.py
+++ b/aria/parser/reading/locator.py
@@ -124,7 +124,7 @@ class Locator(object):
 
 def deepcopy_with_locators(value):
     """
-    Like :code:`deepcopy`, but also copies over locators.
+    Like :func:`deepcopy`, but also copies over locators.
     """
 
     res = deepcopy(value)
@@ -134,7 +134,7 @@ def deepcopy_with_locators(value):
 
 def copy_locators(target, source):
     """
-    Copies over :code:`_locator` for all elements, recursively.
+    Copies over ``_locator`` for all elements, recursively.
 
     Assumes that target and source have exactly the same list/dict structure.
     """

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/parser/reading/reader.py
----------------------------------------------------------------------
diff --git a/aria/parser/reading/reader.py b/aria/parser/reading/reader.py
index fe64697..1a29f11 100644
--- a/aria/parser/reading/reader.py
+++ b/aria/parser/reading/reader.py
@@ -18,7 +18,7 @@ class Reader(object):
     """
     Base class for ARIA readers.
 
-    Readers provide agnostic raw data by consuming :class:`aria.loading.Loader` instances.
+    Readers provide agnostic raw data by consuming :class:`aria.parser.loading.Loader` instances.
     """
 
     def __init__(self, context, location, loader):

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/parser/specification.py
----------------------------------------------------------------------
diff --git a/aria/parser/specification.py b/aria/parser/specification.py
index 714bed1..4f452b8 100644
--- a/aria/parser/specification.py
+++ b/aria/parser/specification.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Utilities for cross-referencing code with specification documents.
+"""
+
 import re
 
 from ..extension import parser

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/parser/validation/__init__.py
----------------------------------------------------------------------
diff --git a/aria/parser/validation/__init__.py b/aria/parser/validation/__init__.py
index fead43b..21632ba 100644
--- a/aria/parser/validation/__init__.py
+++ b/aria/parser/validation/__init__.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Validation package.
+"""
+
 from .issue import Issue
 from .context import ValidationContext
 

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/parser/validation/context.py
----------------------------------------------------------------------
diff --git a/aria/parser/validation/context.py b/aria/parser/validation/context.py
index d81f1cd..ef641bd 100644
--- a/aria/parser/validation/context.py
+++ b/aria/parser/validation/context.py
@@ -23,13 +23,16 @@ from ...utils.formatting import as_raw
 
 class ValidationContext(object):
     """
-    Properties:
+    Validation context.
 
-    * :code:`allow_unknown_fields`: When False (the default) will report an issue
-            if an unknown field is used
-    * :code:`allow_primitive_coersion`: When False (the default) will not attempt to
-            coerce primitive field types
-    * :code:`max_level`: Maximum validation level to report (default is all)
+    :ivar allow_unknown_fields: when ``False`` (the default) will report an issue if an unknown
+     field is used
+    :vartype allow_unknown_fields: bool
+    :ivar allow_primitive_coersion`: when ``False`` (the default) will not attempt to coerce
+     primitive field types
+    :vartype allow_primitive_coersion: bool
+    :ivar max_level: maximum validation level to report (default is all)
+    :vartype max_level: int
     """
 
     def __init__(self):

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/storage/__init__.py
----------------------------------------------------------------------
diff --git a/aria/storage/__init__.py b/aria/storage/__init__.py
index bd7c8c1..a553ca7 100644
--- a/aria/storage/__init__.py
+++ b/aria/storage/__init__.py
@@ -14,29 +14,9 @@
 # limitations under the License.
 
 """
-ARIA's storage Sub-Package
-Path: aria.storage
-
-Storage package is a generic abstraction over different storage types.
-We define this abstraction with the following components:
-
-1. storage: simple mapi to use
-2. driver: implementation of the database client mapi.
-3. model: defines the structure of the table/document.
-4. field: defines a field/item in the model.
-
-API:
-    * application_storage_factory - function, default ARIA storage factory.
-    * Storage - class, simple storage mapi.
-    * models - module, default ARIA standard models.
-    * structures - module, default ARIA structures - holds the base model,
-                   and different fields types.
-    * Model - class, abstract model implementation.
-    * Field - class, base field implementation.
-    * IterField - class, base iterable field implementation.
-    * drivers - module, a pool of ARIA standard drivers.
-    * StorageDriver - class, abstract model implementation.
+Storage package.
 """
+
 from .core import (
     Storage,
     ModelStorage,

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/storage/api.py
----------------------------------------------------------------------
diff --git a/aria/storage/api.py b/aria/storage/api.py
index 3304721..a337743 100644
--- a/aria/storage/api.py
+++ b/aria/storage/api.py
@@ -12,15 +12,17 @@
 # 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.
+
 """
-General storage API
+Storage APIs.
 """
+
 import threading
 
 
 class StorageAPI(object):
     """
-    General storage Base API
+    Base class for storage APIs.
     """
     def create(self, **kwargs):
         """
@@ -33,15 +35,12 @@ class StorageAPI(object):
 
 class ModelAPI(StorageAPI):
     """
-    A Base object for the model.
+    Base class for model APIs ("MAPI").
     """
     def __init__(self, model_cls, name=None, **kwargs):
         """
-        Base model API
-
-        :param model_cls: the representing class of the model
-        :param str name: the name of the model
-        :param kwargs:
+        :param model_cls: representing class of the model
+        :param name: name of the model
         """
         super(ModelAPI, self).__init__(**kwargs)
         self._model_cls = model_cls
@@ -59,46 +58,42 @@ class ModelAPI(StorageAPI):
     @property
     def name(self):
         """
-        The name of the class
-        :return: name of the class
+        Name of the class.
+
+        :type: :obj:`basestring`
         """
         return self._name
 
     @property
     def model_cls(self):
         """
-        The class represting the model
-        :return:
+        Class representing the model
+
+        :type: :obj:`Type`
         """
         return self._model_cls
 
     def get(self, entry_id, filters=None, **kwargs):
         """
-        Get entry from storage.
+        Gets a model from storage.
 
         :param entry_id:
-        :param kwargs:
-        :return:
         """
         raise NotImplementedError('Subclass must implement abstract get method')
 
     def put(self, entry, **kwargs):
         """
-        Store entry in storage
+        Puts a model in storage.
 
         :param entry:
-        :param kwargs:
-        :return:
         """
         raise NotImplementedError('Subclass must implement abstract store method')
 
     def delete(self, entry_id, **kwargs):
         """
-        Delete entry from storage.
+        Deletes a model from storage.
 
         :param entry_id:
-        :param kwargs:
-        :return:
         """
         raise NotImplementedError('Subclass must implement abstract delete method')
 
@@ -107,32 +102,27 @@ class ModelAPI(StorageAPI):
 
     def iter(self, **kwargs):
         """
-        Iter over the entries in storage.
-
-        :param kwargs:
-        :return:
+        Iterate over all models in storage.
         """
         raise NotImplementedError('Subclass must implement abstract iter method')
 
     def update(self, entry, **kwargs):
         """
-        Update entry in storage.
+        Update a model in storage.
 
         :param entry:
         :param kwargs:
-        :return:
         """
         raise NotImplementedError('Subclass must implement abstract update method')
 
 
 class ResourceAPI(StorageAPI):
     """
-    A Base object for the resource.
+    Base class for resource APIs ("RAPI").
     """
     def __init__(self, name, **kwargs):
         """
-        Base resource API
-        :param str name: the resource type
+        :param name: resource type
         """
         super(ResourceAPI, self).__init__(**kwargs)
         self._name = name
@@ -140,63 +130,57 @@ class ResourceAPI(StorageAPI):
     @property
     def name(self):
         """
-        The name of the resource
-        :return:
+        Name of resource.
+
+        :type: :obj:`basestring`
         """
         return self._name
 
     def read(self, entry_id, path, **kwargs):
         """
-        Get a bytesteam from the storage.
+        Get a bytesteam for a resource from storage.
 
         :param entry_id:
         :param path:
-        :param kwargs:
-        :return:
         """
         raise NotImplementedError('Subclass must implement abstract read method')
 
     def delete(self, entry_id, path, **kwargs):
         """
-        Delete a resource from the storage.
+        Delete a resource from storage.
 
         :param entry_id:
         :param path:
-        :param kwargs:
-        :return:
         """
         raise NotImplementedError('Subclass must implement abstract delete method')
 
     def download(self, entry_id, destination, path=None, **kwargs):
         """
-        Download a resource from the storage.
+        Download a resource from storage.
 
         :param entry_id:
         :param destination:
         :param path:
-        :param kwargs:
-        :return:
         """
         raise NotImplementedError('Subclass must implement abstract download method')
 
     def upload(self, entry_id, source, path=None, **kwargs):
         """
-        Upload a resource to the storage.
+        Upload a resource to storage.
 
         :param entry_id:
         :param source:
         :param path:
-        :param kwargs:
-        :return:
         """
         raise NotImplementedError('Subclass must implement abstract upload method')
 
 
 def generate_lower_name(model_cls):
     """
-    Generates the name of the class from the class object. e.g. SomeClass -> some_class
-    :param model_cls: the class to evaluate.
-    :return: lower name
+    Generates the name of the class from the class object, e.g. ``SomeClass`` -> ``some_class``
+
+    :param model_cls: class to evaluate
+    :return: lowercase name
     :rtype: basestring
     """
     return getattr(model_cls, '__mapiname__', model_cls.__tablename__)

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/storage/collection_instrumentation.py
----------------------------------------------------------------------
diff --git a/aria/storage/collection_instrumentation.py b/aria/storage/collection_instrumentation.py
index 454f97a..c90cb18 100644
--- a/aria/storage/collection_instrumentation.py
+++ b/aria/storage/collection_instrumentation.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Utilities for instrumenting collections of models in storage.
+"""
+
 from . import exceptions
 
 
@@ -42,17 +46,15 @@ class _InstrumentedCollection(object):
         Instantiates the object from existing seq.
 
         :param seq: the original sequence to load from
-        :return:
         """
         raise NotImplementedError
 
     def _set(self, key, value):
         """
-        set the changes for the current object (not in the db)
+        Sets the changes for the current object (not in the database).
 
         :param key:
         :param value:
-        :return:
         """
         raise NotImplementedError
 
@@ -61,10 +63,10 @@ class _InstrumentedCollection(object):
 
     def _instrument(self, key, value):
         """
-        Instruments any collection to track changes (and ease of access)
+        Instruments any collection to track changes (and ease of access).
+
         :param key:
         :param value:
-        :return:
         """
         if isinstance(value, _InstrumentedCollection):
             return value
@@ -79,9 +81,9 @@ class _InstrumentedCollection(object):
 
     def _raw_value(self, value):
         """
-        Get the raw value.
+        Gets the raw value.
+
         :param value:
-        :return:
         """
         if isinstance(value, self._field_cls):
             return value.value
@@ -89,10 +91,10 @@ class _InstrumentedCollection(object):
 
     def _encapsulate_value(self, key, value):
         """
-        Create a new item cls if needed.
+        Creates a new item class if needed.
+
         :param key:
         :param value:
-        :return:
         """
         if isinstance(value, self._field_cls):
             return value
@@ -101,10 +103,10 @@ class _InstrumentedCollection(object):
 
     def __setitem__(self, key, value):
         """
-        Update the values in both the local and the db locations.
+        Updates the values in both the local and the database locations.
+
         :param key:
         :param value:
-        :return:
         """
         self._set(key, value)
         if self._is_top_level:
@@ -119,11 +121,11 @@ class _InstrumentedCollection(object):
 
     def _set_field(self, collection, key, value):
         """
-        enables updating the current change in the ancestors
-        :param collection: the collection to change
-        :param key: the key for the specific field
-        :param value: the new value
-        :return:
+        Enables updating the current change in the ancestors.
+
+        :param collection: collection to change
+        :param key: key for the specific field
+        :param value: new value
         """
         if isinstance(value, _InstrumentedCollection):
             value = value._raw
@@ -209,9 +211,10 @@ class _InstrumentedModel(_WrappedBase):
 
     def __init__(self, mapi, *args, **kwargs):
         """
-        The original model
-        :param wrapped: the model to be instrumented
-        :param mapi: the mapi for that model
+        The original model.
+
+        :param wrapped: model to be instrumented
+        :param mapi: MAPI for the wrapped model
         """
         super(_InstrumentedModel, self).__init__(*args, **kwargs)
         self._mapi = mapi
@@ -261,11 +264,10 @@ class _WrappedModel(_WrappedBase):
 
     def __init__(self, instrumentation_kwargs, *args, **kwargs):
         """
-
-        :param instrumented_cls: The class to be instrumented
-        :param instrumentation_cls: the instrumentation cls
-        :param wrapped: the currently wrapped instance
-        :param kwargs: and kwargs to the passed to the instrumented class.
+        :param instrumented_cls: class to be instrumented
+        :param instrumentation_cls: instrumentation cls
+        :param wrapped: currently wrapped instance
+        :param kwargs: passed to the instrumented class
         """
         super(_WrappedModel, self).__init__(*args, **kwargs)
         self._kwargs = instrumentation_kwargs

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/storage/core.py
----------------------------------------------------------------------
diff --git a/aria/storage/core.py b/aria/storage/core.py
index 06c29e8..74b1147 100644
--- a/aria/storage/core.py
+++ b/aria/storage/core.py
@@ -14,29 +14,9 @@
 # limitations under the License.
 
 """
-ARIA's storage Sub-Package
-Path: aria.storage
-
-Storage package is a generic abstraction over different storage types.
-We define this abstraction with the following components:
-
-1. storage: simple mapi to use
-2. driver: implementation of the database client mapi.
-3. model: defines the structure of the table/document.
-4. field: defines a field/item in the model.
-
-API:
-    * application_storage_factory - function, default ARIA storage factory.
-    * Storage - class, simple storage mapi.
-    * models - module, default ARIA standard models.
-    * structures - module, default ARIA structures - holds the base model,
-                   and different fields types.
-    * Model - class, abstract model implementation.
-    * Field - class, base field implementation.
-    * IterField - class, base iterable field implementation.
-    * drivers - module, a pool of ARIA standard drivers.
-    * StorageDriver - class, abstract model implementation.
+Storage API management.
 """
+
 import copy
 from contextlib import contextmanager
 
@@ -52,7 +32,7 @@ __all__ = (
 
 class Storage(LoggerMixin):
     """
-    Represents the storage
+    Base class for storage managers.
     """
     def __init__(self,
                  api_cls,
@@ -62,13 +42,12 @@ class Storage(LoggerMixin):
                  initiator_kwargs=None,
                  **kwargs):
         """
-
-        :param api_cls: API cls for each model.
+        :param api_cls: API class for each entry
         :param api_kwargs:
-        :param items: the items to register
-        :param initiator: a func which initializes the storage before the first use.
-        This function should return a dict, this dict would be passed in addition to the api kwargs.
-        This enables the creation of any unpickable objects across process.
+        :param items: items to register
+        :param initiator: function which initializes the storage before the first use; this function
+         should return a dict, this dict would be passed in addition to the API kwargs; this enables
+         the creation of non-serializable objects
         :param initiator_kwargs:
         :param kwargs:
         """
@@ -112,22 +91,22 @@ class Storage(LoggerMixin):
 
     def register(self, entry):
         """
-        Register the entry to the storage
-        :param name:
-        :return:
+        Register an API.
+
+        :param entry:
         """
         raise NotImplementedError('Subclass must implement abstract register method')
 
 
 class ResourceStorage(Storage):
     """
-    Represents resource storage.
+    Manages storage resource APIs ("RAPIs").
     """
     def register(self, name):
         """
-        Register the resource type to resource storage.
-        :param name:
-        :return:
+        Register a storage resource API ("RAPI").
+
+        :param name: name
         """
         self.registered[name] = self.api(name=name, **self._all_api_kwargs)
         self.registered[name].create()
@@ -136,7 +115,7 @@ class ResourceStorage(Storage):
 
 class ModelStorage(Storage):
     """
-    Represents model storage.
+    Manages storage model APIs ("MAPIs").
     """
     def __init__(self, *args, **kwargs):
         if kwargs.get('initiator', None) is None:
@@ -145,9 +124,9 @@ class ModelStorage(Storage):
 
     def register(self, model_cls):
         """
-        Register the model into the model storage.
-        :param model_cls: the model to register.
-        :return:
+        Register a storage model API ("MAPI").
+
+        :param model_cls: model API to register
         """
         model_name = model_cls.__modelname__
         if model_name in self.registered:
@@ -162,8 +141,7 @@ class ModelStorage(Storage):
 
     def drop(self):
         """
-        Drop all the tables from the model.
-        :return:
+        Drop all the tables.
         """
         for mapi in self.registered.values():
             mapi.drop()

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/storage/exceptions.py
----------------------------------------------------------------------
diff --git a/aria/storage/exceptions.py b/aria/storage/exceptions.py
index 3f0ecec..c538876 100644
--- a/aria/storage/exceptions.py
+++ b/aria/storage/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.
+
 """
-Storage based exceptions
+Storage exceptions.
 """
+
 from .. import exceptions
 
 

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/storage/filesystem_rapi.py
----------------------------------------------------------------------
diff --git a/aria/storage/filesystem_rapi.py b/aria/storage/filesystem_rapi.py
index 3ddc520..b425fa2 100644
--- a/aria/storage/filesystem_rapi.py
+++ b/aria/storage/filesystem_rapi.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.
+
 """
-File system based RAPI
+File system implementation of the storage resource API ("RAPI").
 """
+
 import os
 import shutil
 from multiprocessing import RLock
@@ -30,13 +32,12 @@ from aria.storage import (
 
 class FileSystemResourceAPI(api.ResourceAPI):
     """
-    File system resource storage.
+    File system implementation of the storage resource API ("RAPI").
     """
 
     def __init__(self, directory, **kwargs):
         """
-        File system implementation for storage api.
-        :param str directory: root dir for storage.
+        :param directory: root dir for storage
         """
         super(FileSystemResourceAPI, self).__init__(**kwargs)
         self.directory = directory
@@ -47,8 +48,7 @@ class FileSystemResourceAPI(api.ResourceAPI):
     @contextmanager
     def connect(self):
         """
-        Established a connection and destroys it after use.
-        :return:
+        Establishes a connection and destroys it after use.
         """
         try:
             self._establish_connection()
@@ -60,16 +60,13 @@ class FileSystemResourceAPI(api.ResourceAPI):
 
     def _establish_connection(self):
         """
-        Establish a conenction. used in the 'connect' contextmanager.
-        :return:
+        Establishes a connection. Used in the ``connect`` context manager.
         """
         self._lock.acquire()
 
-
     def _destroy_connection(self):
         """
-        Destroy a connection. used in the 'connect' contextmanager.
-        :return:
+        Destroys a connection. Used in the ``connect`` context manager.
         """
         self._lock.release()
 
@@ -79,9 +76,9 @@ class FileSystemResourceAPI(api.ResourceAPI):
 
     def create(self, **kwargs):
         """
-        Create directory in storage by path.
-        tries to create the root directory as well.
-        :param str name: path of file in storage.
+        Creates a directory in by path. Tries to create the root directory as well.
+
+        :param name: path of directory
         """
         try:
             os.makedirs(self.directory)
@@ -94,11 +91,11 @@ class FileSystemResourceAPI(api.ResourceAPI):
 
     def read(self, entry_id, path, **_):
         """
-        Retrieve the content of a file system storage resource.
+        Retrieves the contents of a file.
 
-        :param str entry_id: the id of the entry.
-        :param str path: a path to the specific resource to read.
-        :return: the content of the file.
+        :param entry_id: entry ID
+        :param path: path to resource
+        :return: contents of the file
         :rtype: bytes
         """
         resource_relative_path = os.path.join(self.name, entry_id, path or '')
@@ -118,11 +115,11 @@ class FileSystemResourceAPI(api.ResourceAPI):
 
     def download(self, entry_id, destination, path=None, **_):
         """
-        Download a specific file or dir from the file system resource storage.
+        Downloads a file or directory.
 
-        :param str entry_id: the id of the entry.
-        :param str destination: the destination to download to
-        :param str path: the path to download relative to the root of the entry (otherwise all).
+        :param entry_id: entry ID
+        :param destination: download destination
+        :param path: path to download relative to the root of the entry (otherwise all)
         """
         resource_relative_path = os.path.join(self.name, entry_id, path or '')
         resource = os.path.join(self.directory, resource_relative_path)
@@ -136,10 +133,10 @@ class FileSystemResourceAPI(api.ResourceAPI):
 
     def upload(self, entry_id, source, path=None, **_):
         """
-        Uploads a specific file or dir to the file system resource storage.
+        Uploads a file or directory.
 
-        :param str entry_id: the id of the entry.
-        :param source: the source of the files to upload.
+        :param entry_id: entry ID
+        :param source: source of the files to upload
         :param path: the destination of the file/s relative to the entry root dir.
         """
         resource_directory = os.path.join(self.directory, self.name, entry_id)
@@ -153,10 +150,10 @@ class FileSystemResourceAPI(api.ResourceAPI):
 
     def delete(self, entry_id, path=None, **_):
         """
-        Deletes a file system storage resource.
+        Deletes a file or directory.
 
-        :param str entry_id: the id of the entry.
-        :param str path: a path to delete relative to the root of the entry (otherwise all).
+        :param entry_id: entry ID
+        :param path: path to delete relative to the root of the entry (otherwise all)
         """
         destination = os.path.join(self.directory, self.name, entry_id, path or '')
         if os.path.exists(destination):

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/storage/sql_mapi.py
----------------------------------------------------------------------
diff --git a/aria/storage/sql_mapi.py b/aria/storage/sql_mapi.py
index bb6223a..975ada7 100644
--- a/aria/storage/sql_mapi.py
+++ b/aria/storage/sql_mapi.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.
+
 """
-SQLAlchemy based MAPI
+SQLAlchemy implementation of the storage model API ("MAPI").
 """
+
 import os
 import platform
 
@@ -42,7 +44,7 @@ _predicates = {'ge': '__ge__',
 
 class SQLAlchemyModelAPI(api.ModelAPI):
     """
-    SQL based MAPI.
+    SQLAlchemy implementation of the storage model API ("MAPI").
     """
 
     def __init__(self,
@@ -54,7 +56,8 @@ class SQLAlchemyModelAPI(api.ModelAPI):
         self._session = session
 
     def get(self, entry_id, include=None, **kwargs):
-        """Return a single result based on the model class and element ID
+        """
+        Returns a single result based on the model class and element ID
         """
         query = self._get_query(include, {'id': entry_id})
         result = query.first()
@@ -102,25 +105,28 @@ class SQLAlchemyModelAPI(api.ModelAPI):
              filters=None,
              sort=None,
              **kwargs):
-        """Return a (possibly empty) list of `model_class` results
+        """
+        Returns a (possibly empty) list of ``model_class`` results.
         """
         for result in self._get_query(include, filters, sort):
             yield self._instrument(result)
 
     def put(self, entry, **kwargs):
-        """Create a `model_class` instance from a serializable `model` object
+        """
+        Creatse a ``model_class`` instance from a serializable ``model`` object.
 
-        :param entry: A dict with relevant kwargs, or an instance of a class
-        that has a `to_dict` method, and whose attributes match the columns
-        of `model_class` (might also my just an instance of `model_class`)
-        :return: An instance of `model_class`
+        :param entry: dict with relevant kwargs, or an instance of a class that has a ``to_dict``
+         method, and whose attributes match the columns of ``model_class`` (might also be just an
+         instance of ``model_class``)
+        :return: an instance of ``model_class``
         """
         self._session.add(entry)
         self._safe_commit()
         return entry
 
     def delete(self, entry, **kwargs):
-        """Delete a single result based on the model class and element ID
+        """
+        Deletes a single result based on the model class and element ID.
         """
         self._load_relationships(entry)
         self._session.delete(entry)
@@ -128,17 +134,19 @@ class SQLAlchemyModelAPI(api.ModelAPI):
         return entry
 
     def update(self, entry, **kwargs):
-        """Add `instance` to the DB session, and attempt to commit
+        """
+        Adds ``instance`` to the database session, and attempts to commit.
 
-        :return: The updated instance
+        :return: updated instance
         """
         return self.put(entry)
 
     def refresh(self, entry):
-        """Reload the instance with fresh information from the DB
+        """
+        Reloads the instance with fresh information from the database.
 
-        :param entry: Instance to be re-loaded from the DB
-        :return: The refreshed instance
+        :param entry: instance to be re-loaded from the database
+        :return: refreshed instance
         """
         self._session.refresh(entry)
         self._load_relationships(entry)
@@ -160,14 +168,14 @@ class SQLAlchemyModelAPI(api.ModelAPI):
 
     def drop(self):
         """
-        Drop the table from the storage.
-        :return:
+        Drops the table.
         """
         self.model_cls.__table__.drop(self._engine)
 
     def _safe_commit(self):
-        """Try to commit changes in the session. Roll back if exception raised
-        Excepts SQLAlchemy errors and rollbacks if they're caught
+        """
+        Try to commit changes in the session. Roll back if exception raised SQLAlchemy errors and
+        rolls back if they're caught.
         """
         try:
             self._session.commit()
@@ -179,11 +187,11 @@ class SQLAlchemyModelAPI(api.ModelAPI):
             raise exceptions.StorageError('SQL Storage error: {0}'.format(str(e)))
 
     def _get_base_query(self, include, joins):
-        """Create the initial query from the model class and included columns
+        """
+        Create the initial query from the model class and included columns.
 
-        :param include: A (possibly empty) list of columns to include in
-        the query
-        :return: An SQLAlchemy AppenderQuery object
+        :param include: (possibly empty) list of columns to include in the query
+        :return: SQLAlchemy AppenderQuery object
         """
         # If only some columns are included, query through the session object
         if include:
@@ -199,9 +207,10 @@ class SQLAlchemyModelAPI(api.ModelAPI):
 
     @staticmethod
     def _get_joins(model_class, columns):
-        """Get a list of all the tables on which we need to join
+        """
+        Gets a list of all the tables on which we need to join.
 
-        :param columns: A set of all attributes involved in the query
+        :param columns: set of all attributes involved in the query
         """
 
         # Using a list instead of a set because order is important
@@ -222,12 +231,13 @@ class SQLAlchemyModelAPI(api.ModelAPI):
 
     @staticmethod
     def _sort_query(query, sort=None):
-        """Add sorting clauses to the query
+        """
+        Adds sorting clauses to the query.
 
-        :param query: Base SQL query
-        :param sort: An optional dictionary where keys are column names to
-        sort by, and values are the order (asc/desc)
-        :return: An SQLAlchemy AppenderQuery object
+        :param query: base SQL query
+        :param sort: optional dictionary where keys are column names to sort by, and values are
+         the order (asc/desc)
+        :return: SQLAlchemy AppenderQuery object
         """
         if sort:
             for column, order in sort.items():
@@ -237,13 +247,13 @@ class SQLAlchemyModelAPI(api.ModelAPI):
         return query
 
     def _filter_query(self, query, filters):
-        """Add filter clauses to the query
+        """
+        Adds filter clauses to the query.
 
-        :param query: Base SQL query
-        :param filters: An optional dictionary where keys are column names to
-        filter by, and values are values applicable for those columns (or lists
-        of such values)
-        :return: An SQLAlchemy AppenderQuery object
+        :param query: base SQL query
+        :param filters: optional dictionary where keys are column names to filter by, and values
+         are values applicable for those columns (or lists of such values)
+        :return: SQLAlchemy AppenderQuery object
         """
         return self._add_value_filter(query, filters)
 
@@ -264,17 +274,16 @@ class SQLAlchemyModelAPI(api.ModelAPI):
                    include=None,
                    filters=None,
                    sort=None):
-        """Get an SQL query object based on the params passed
-
-        :param model_class: SQL DB table class
-        :param include: An optional list of columns to include in the query
-        :param filters: An optional dictionary where keys are column names to
-        filter by, and values are values applicable for those columns (or lists
-        of such values)
-        :param sort: An optional dictionary where keys are column names to
-        sort by, and values are the order (asc/desc)
-        :return: A sorted and filtered query with only the relevant
-        columns
+        """
+        Gets a SQL query object based on the params passed.
+
+        :param model_class: SQL database table class
+        :param include: optional list of columns to include in the query
+        :param filters: optional dictionary where keys are column names to filter by, and values
+         are values applicable for those columns (or lists of such values)
+        :param sort: optional dictionary where keys are column names to sort by, and values are the
+         order (asc/desc)
+        :return: sorted and filtered query with only the relevant columns
         """
         include, filters, sort, joins = self._get_joins_and_converted_columns(
             include, filters, sort
@@ -305,9 +314,10 @@ class SQLAlchemyModelAPI(api.ModelAPI):
                                          include,
                                          filters,
                                          sort):
-        """Get a list of tables on which we need to join and the converted
-        `include`, `filters` and `sort` arguments (converted to actual SQLA
-        column/label objects instead of column names)
+        """
+        Gets a list of tables on which we need to join and the converted ``include``, ``filters``
+        and ```sort`` arguments (converted to actual SQLAlchemy column/label objects instead of
+        column names).
         """
         include = include or []
         filters = filters or dict()
@@ -325,8 +335,9 @@ class SQLAlchemyModelAPI(api.ModelAPI):
                                       include,
                                       filters,
                                       sort):
-        """Go over the optional parameters (include, filters, sort), and
-        replace column names with actual SQLA column objects
+        """
+        Gooes over the optional parameters (include, filters, sort), and replace column names with
+        actual SQLAlechmy column objects.
         """
         include = [self._get_column(c) for c in include]
         filters = dict((self._get_column(c), filters[c]) for c in filters)
@@ -335,9 +346,10 @@ class SQLAlchemyModelAPI(api.ModelAPI):
         return include, filters, sort
 
     def _get_column(self, column_name):
-        """Return the column on which an action (filtering, sorting, etc.)
-        would need to be performed. Can be either an attribute of the class,
-        or an association proxy linked to a relationship the class has
+        """
+        Returns the column on which an action (filtering, sorting, etc.) would need to be performed.
+        Can be either an attribute of the class, or an association proxy linked to a relationship
+        in the class.
         """
         column = getattr(self.model_cls, column_name)
         if column.is_attribute:
@@ -352,15 +364,16 @@ class SQLAlchemyModelAPI(api.ModelAPI):
 
     @staticmethod
     def _paginate(query, pagination):
-        """Paginate the query by size and offset
-
-        :param query: Current SQLAlchemy query object
-        :param pagination: An optional dict with size and offset keys
-        :return: A tuple with four elements:
-        - res ults: `size` items starting from `offset`
-        - the total count of items
-        - `size` [default: 0]
-        - `offset` [default: 0]
+        """
+        Paginates the query by size and offset.
+
+        :param query: current SQLAlchemy query object
+        :param pagination: optional dict with size and offset keys
+        :return: tuple with four elements:
+         * results: ``size`` items starting from ``offset``
+         * the total count of items
+         * ``size`` [default: 0]
+         * ``offset`` [default: 0]
         """
         if pagination:
             size = pagination.get('size', 0)
@@ -374,8 +387,9 @@ class SQLAlchemyModelAPI(api.ModelAPI):
 
     @staticmethod
     def _load_relationships(instance):
-        """A helper method used to overcome a problem where the relationships
-        that rely on joins aren't being loaded automatically
+        """
+        Helper method used to overcome a problem where the relationships that rely on joins aren't
+        being loaded automatically.
         """
         for rel in instance.__mapper__.relationships:
             getattr(instance, rel.key)
@@ -389,13 +403,15 @@ class SQLAlchemyModelAPI(api.ModelAPI):
 
 def init_storage(base_dir, filename='db.sqlite'):
     """
-    A builtin ModelStorage initiator.
-    Creates a sqlalchemy engine and a session to be passed to the mapi.
+    Built-in ModelStorage initiator.
+
+    Creates a SQLAlchemy engine and a session to be passed to the MAPI.
+
+    ``initiator_kwargs`` must be passed to the ModelStorage which must hold the ``base_dir`` for the
+    location of the database file, and an option filename. This would create an SQLite database.
 
-    Initiator_kwargs must be passed to the ModelStorage which must hold the base_dir for the
-    location of the db file, and an option filename. This would create an sqlite db.
-    :param base_dir: the dir of the db
-    :param filename: the db file name.
+    :param base_dir: directory of the database
+    :param filename: database file name.
     :return:
     """
     uri = 'sqlite:///{platform_char}{path}'.format(
@@ -415,7 +431,7 @@ def init_storage(base_dir, filename='db.sqlite'):
 
 class ListResult(list):
     """
-    a ListResult contains results about the requested items.
+    Contains results about the requested items.
     """
     def __init__(self, metadata, *args, **qwargs):
         super(ListResult, self).__init__(*args, **qwargs)

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/utils/__init__.py
----------------------------------------------------------------------
diff --git a/aria/utils/__init__.py b/aria/utils/__init__.py
index ae1e83e..2a957a9 100644
--- a/aria/utils/__init__.py
+++ b/aria/utils/__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.
+
+"""
+General-purpose utilities package.
+"""

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/utils/archive.py
----------------------------------------------------------------------
diff --git a/aria/utils/archive.py b/aria/utils/archive.py
index 63d9004..29efcb1 100644
--- a/aria/utils/archive.py
+++ b/aria/utils/archive.py
@@ -10,6 +10,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Archive utilities.
+"""
 
 import os
 import tarfile

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/utils/argparse.py
----------------------------------------------------------------------
diff --git a/aria/utils/argparse.py b/aria/utils/argparse.py
index 365c148..a05a841 100644
--- a/aria/utils/argparse.py
+++ b/aria/utils/argparse.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Enhancements to Python's ``argparse`` module.
+"""
+
 from __future__ import absolute_import  # so we can import standard 'argparse'
 
 from argparse import ArgumentParser as BaseArgumentParser
@@ -27,7 +31,7 @@ class ArgumentParser(BaseArgumentParser):
 
     def add_flag_argument(self, name, help_true=None, help_false=None, default=False):
         """
-        Adds a flag argument as two arguments: :code:`--my-flag` and :code:`--no-my-flag`.
+        Adds a flag argument as two arguments: ``--my-flag`` and ``--no-my-flag``.
         """
 
         dest = name.replace('-', '_')

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/utils/caching.py
----------------------------------------------------------------------
diff --git a/aria/utils/caching.py b/aria/utils/caching.py
index c9e475a..5f8cd88 100644
--- a/aria/utils/caching.py
+++ b/aria/utils/caching.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Caching utilities.
+"""
+
 from __future__ import absolute_import  # so we can import standard 'collections' and 'threading'
 
 from threading import Lock
@@ -27,8 +31,8 @@ class cachedmethod(object):  # pylint: disable=invalid-name
 
     The implementation is thread-safe.
 
-    Supports :code:`cache_info` to be compatible with Python 3's :code:`functools.lru_cache`.
-    Note that the statistics are combined for all instances of the class.
+    Supports ``cache_info`` to be compatible with Python 3's ``functools.lru_cache``. Note that the
+    statistics are combined for all instances of the class.
 
     Won't use the cache if not called when bound to an object, allowing you to override the cache.
 
@@ -39,6 +43,7 @@ class cachedmethod(object):  # pylint: disable=invalid-name
     ENABLED = True
 
     def __init__(self, func):
+        self.__doc__ = func.__doc__
         self.func = func
         self.hits = 0
         self.misses = 0

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/utils/collections.py
----------------------------------------------------------------------
diff --git a/aria/utils/collections.py b/aria/utils/collections.py
index 1e732aa..ccc37a1 100644
--- a/aria/utils/collections.py
+++ b/aria/utils/collections.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Additional collection classes and collection utilities.
+"""
+
 from __future__ import absolute_import  # so we can import standard 'collections'
 
 from copy import deepcopy
@@ -32,8 +36,8 @@ class FrozenList(list):
     """
     An immutable list.
 
-    After initialization it will raise :class:`TypeError` exceptions if modification
-    is attempted.
+    After initialization it will raise :class:`~exceptions.TypeError` exceptions if modification is
+    attempted.
 
     Note that objects stored in the list may not be immutable.
     """
@@ -78,12 +82,13 @@ class FrozenList(list):
 
 EMPTY_READ_ONLY_LIST = FrozenList()
 
+
 class FrozenDict(OrderedDict):
     """
     An immutable ordered dict.
 
-    After initialization it will raise :class:`TypeError` exceptions if modification
-    is attempted.
+    After initialization it will raise :class:`~exceptions.TypeError` exceptions if modification is
+    attempted.
 
     Note that objects stored in the dict may not be immutable.
     """
@@ -109,9 +114,11 @@ class FrozenDict(OrderedDict):
 
 EMPTY_READ_ONLY_DICT = FrozenDict()
 
+
 class StrictList(list):
     """
-    A list that raises :class:`TypeError` exceptions when objects of the wrong type are inserted.
+    A list that raises :class:`~exceptions.TypeError` exceptions when objects of the wrong type are
+    inserted.
     """
 
     def __init__(self,
@@ -168,10 +175,11 @@ class StrictList(list):
         value = self._wrap(value)
         return super(StrictList, self).insert(index, value)
 
+
 class StrictDict(OrderedDict):
     """
-    An ordered dict that raises :class:`TypeError` exceptions
-    when keys or values of the wrong type are used.
+    An ordered dict that raises :class:`~exceptions.TypeError` exceptions when keys or values of the
+    wrong type are used.
     """
 
     def __init__(self,
@@ -211,6 +219,7 @@ class StrictDict(OrderedDict):
             value = self.wrapper_function(value)
         return super(StrictDict, self).__setitem__(key, value)
 
+
 def merge(dict_a, dict_b, path=None, strict=False):
     """
     Merges dicts, recursively.
@@ -234,12 +243,14 @@ def merge(dict_a, dict_b, path=None, strict=False):
             dict_a[key] = value_b
     return dict_a
 
+
 def is_removable(_container, _key, v):
     return (v is None) or ((isinstance(v, dict) or isinstance(v, list)) and (len(v) == 0))
 
+
 def prune(value, is_removable_function=is_removable):
     """
-    Deletes :code:`None` and empty lists and dicts, recursively.
+    Deletes ``None`` and empty lists and dicts, recursively.
     """
 
     if isinstance(value, list):
@@ -258,10 +269,11 @@ def prune(value, is_removable_function=is_removable):
     return value
 
 
-# TODO (left for tal): Move following two methods to some place parser specific
+# TODO: Move following two methods to some place parser specific
+
 def deepcopy_with_locators(value):
     """
-    Like :code:`deepcopy`, but also copies over locators.
+    Like :func:`~copy.deepcopy`, but also copies over locators.
     """
 
     res = deepcopy(value)
@@ -271,7 +283,7 @@ def deepcopy_with_locators(value):
 
 def copy_locators(target, source):
     """
-    Copies over :code:`_locator` for all elements, recursively.
+    Copies over ``_locator`` for all elements, recursively.
 
     Assumes that target and source have exactly the same list/dict structure.
     """

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/utils/console.py
----------------------------------------------------------------------
diff --git a/aria/utils/console.py b/aria/utils/console.py
index 55d2529..642cbb1 100644
--- a/aria/utils/console.py
+++ b/aria/utils/console.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Abstraction API above terminal color libraries.
+"""
+
 from clint.textui.core import STDOUT
 from clint.textui import puts as _puts
 from clint.textui.colored import ColoredString as _ColoredString

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/utils/exceptions.py
----------------------------------------------------------------------
diff --git a/aria/utils/exceptions.py b/aria/utils/exceptions.py
index b60cee4..5bb0e6d 100644
--- a/aria/utils/exceptions.py
+++ b/aria/utils/exceptions.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Utilities for extracting and formatting Python exceptions.
+"""
+
 import sys
 import linecache
 import StringIO

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/utils/file.py
----------------------------------------------------------------------
diff --git a/aria/utils/file.py b/aria/utils/file.py
index 6d1aa16..75f2859 100644
--- a/aria/utils/file.py
+++ b/aria/utils/file.py
@@ -13,13 +13,19 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+File utilities.
+"""
+
 import errno
 import os
 import shutil
 
 
 def makedirs(path):
-    """An extension of os.makedirs that doesn't fail if the directory already exists"""
+    """
+    Enhancement of :func:`os.makedirs` that doesn't fail if the directory already exists.
+    """
     if os.path.isdir(path):
         return
     try:
@@ -29,7 +35,6 @@ def makedirs(path):
             raise
 
 def remove_if_exists(path):
-
     try:
         if os.path.isfile(path):
             os.remove(path)

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/utils/formatting.py
----------------------------------------------------------------------
diff --git a/aria/utils/formatting.py b/aria/utils/formatting.py
index b8d24cd..fa34b7d 100644
--- a/aria/utils/formatting.py
+++ b/aria/utils/formatting.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+String formatting and string-based format utilities.
+"""
+
 import json
 from types import MethodType
 
@@ -42,8 +46,7 @@ yaml.representer.RoundTripRepresenter.add_representer(
 
 class JsonAsRawEncoder(json.JSONEncoder):
     """
-    A :class:`JSONEncoder` that will use the :code:`as_raw` property of objects
-    if available.
+    A :class:`JSONEncoder` that will use the ``as_raw`` property of objects if available.
     """
     def raw_encoder_default(self, obj):
         try:
@@ -61,8 +64,7 @@ class JsonAsRawEncoder(json.JSONEncoder):
 
 class YamlAsRawDumper(yaml.dumper.RoundTripDumper):  # pylint: disable=too-many-ancestors
     """
-    A :class:`RoundTripDumper` that will use the :code:`as_raw` property of objects
-    if available.
+    A :class:`RoundTripDumper` that will use the ``as_raw`` property of objects if available.
     """
 
     def represent_data(self, data):
@@ -101,8 +103,8 @@ def decode_dict(data):
 
 def safe_str(value):
     """
-    Like :code:`str` coercion, but makes sure that Unicode strings are properly
-    encoded, and will never return None.
+    Like :class:`str` coercion, but makes sure that Unicode strings are properly encoded, and will
+    never return ``None``.
     """
 
     try:
@@ -113,7 +115,7 @@ def safe_str(value):
 
 def safe_repr(value):
     """
-    Like :code:`repr`, but calls :code:`as_raw` and :code:`as_agnostic` first.
+    Like :func:`repr`, but calls :func:`as_raw` and :func:`as_agnostic` first.
     """
 
     return repr(as_agnostic(as_raw(value)))
@@ -143,7 +145,7 @@ def pluralize(noun):
 
 def as_raw(value):
     """
-    Converts values using their :code:`as_raw` property, if it exists, recursively.
+    Converts values using their ``as_raw`` property, if it exists, recursively.
     """
 
     if hasattr(value, 'as_raw'):
@@ -164,7 +166,7 @@ def as_raw(value):
 
 def as_raw_list(value):
     """
-    Assuming value is a list, converts its values using :code:`as_raw`.
+    Assuming value is a list, converts its values using :func:`as_raw`.
     """
 
     if value is None:
@@ -176,8 +178,7 @@ def as_raw_list(value):
 
 def as_raw_dict(value):
     """
-    Assuming value is a dict, converts its values using :code:`as_raw`.
-    The keys are left as is.
+    Assuming value is a dict, converts its values using :func:`as_raw`. The keys are left as is.
     """
 
     if value is None:
@@ -188,8 +189,8 @@ def as_raw_dict(value):
 
 def as_agnostic(value):
     """
-    Converts subclasses of list and dict to standard lists and dicts, and Unicode strings
-    to non-Unicode if possible, recursively.
+    Converts subclasses of list and dict to standard lists and dicts, and Unicode strings to
+    non-Unicode if possible, recursively.
 
     Useful for creating human-readable output of structures.
     """
@@ -216,8 +217,7 @@ def as_agnostic(value):
 
 def json_dumps(value, indent=2):
     """
-    JSON dumps that supports Unicode and the :code:`as_raw` property of objects
-    if available.
+    JSON dumps that supports Unicode and the ``as_raw`` property of objects if available.
     """
 
     return json.dumps(value, indent=indent, ensure_ascii=False, cls=JsonAsRawEncoder)
@@ -225,8 +225,7 @@ def json_dumps(value, indent=2):
 
 def yaml_dumps(value, indent=2):
     """
-    YAML dumps that supports Unicode and the :code:`as_raw` property of objects
-    if available.
+    YAML dumps that supports Unicode and the ``as_raw`` property of objects if available.
     """
 
     return yaml.dump(value, indent=indent, allow_unicode=True, Dumper=YamlAsRawDumper)

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/utils/http.py
----------------------------------------------------------------------
diff --git a/aria/utils/http.py b/aria/utils/http.py
index 7bdfd79..c8357e9 100644
--- a/aria/utils/http.py
+++ b/aria/utils/http.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+HTTP utilities.
+"""
+
 import os
 import tempfile
 
@@ -20,17 +24,17 @@ import requests
 
 
 def download_file(url, destination=None, logger=None, progress_handler=None):
-    """Download file.
-
-    May raise IOError as well as requests.exceptions.RequestException
-    :param url: Location of the file to download
-    :type url: str
-    :param destination:
-        Location where the file should be saved (autogenerated by default)
-    :type destination: str | None
-    :returns: Location where the file was saved
-    :rtype: str
+    """
+    Download file.
 
+    :param url: URL from which to download
+    :type url: basestring
+    :param destination: path where the file should be saved or ``None`` to auto-generate
+    :type destination: basestring
+    :returns: path where the file was saved
+    :rtype: basestring
+    :raises exceptions.IOError:
+    :raises requests.exceptions.RequestException:
     """
     chunk_size = 1024
 

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/utils/imports.py
----------------------------------------------------------------------
diff --git a/aria/utils/imports.py b/aria/utils/imports.py
index 35aa0fc..14ad09e 100644
--- a/aria/utils/imports.py
+++ b/aria/utils/imports.py
@@ -14,7 +14,7 @@
 # limitations under the License.
 
 """
-Utility methods for dynamically loading python code
+Utilities for dynamically loading Python code.
 """
 
 import pkgutil
@@ -50,8 +50,8 @@ def import_fullname(name, paths=None):
 
 def import_modules(name):
     """
-    Imports a module and all its sub-modules, recursively.
-    Relies on modules defining a 'MODULES' attribute listing their sub-module names.
+    Imports a module and all its sub-modules, recursively. Relies on modules defining a ``MODULES``
+    attribute listing their sub-module names.
     """
 
     module = __import__(name, fromlist=['MODULES'], level=0)
@@ -63,9 +63,9 @@ def import_modules(name):
 # TODO merge with import_fullname
 def load_attribute(attribute_path):
     """
-    Dynamically load an attribute based on the path to it.
-    e.g. some_package.some_module.some_attribute, will load the some_attribute from the
-    some_package.some_module module
+    Dynamically load an attribute based on the path to it. E.g.
+    ``some_package.some_module.some_attribute``, will load ``some_attribute`` from the
+    ``some_package.some_module`` module.
     """
     module_name, attribute_name = attribute_path.rsplit('.', 1)
     try:

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/utils/openclose.py
----------------------------------------------------------------------
diff --git a/aria/utils/openclose.py b/aria/utils/openclose.py
index 19740eb..722885c 100644
--- a/aria/utils/openclose.py
+++ b/aria/utils/openclose.py
@@ -13,9 +13,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Utilities for working with open/close patterns.
+"""
+
 class OpenClose(object):
     """
-    Wraps an object that has open() and close() methods to support the "with" keyword.
+    Wraps an object that has ``open()`` and ``close()`` methods to support the ``with`` keyword.
     """
 
     def __init__(self, wrapped):

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/utils/plugin.py
----------------------------------------------------------------------
diff --git a/aria/utils/plugin.py b/aria/utils/plugin.py
index b7f94a1..4fb6a8e 100644
--- a/aria/utils/plugin.py
+++ b/aria/utils/plugin.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Plugin utilities.
+"""
+
 import wagon
 
 

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/utils/process.py
----------------------------------------------------------------------
diff --git a/aria/utils/process.py b/aria/utils/process.py
index 9aeae67..ec4a72d 100644
--- a/aria/utils/process.py
+++ b/aria/utils/process.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Process utilities.
+"""
+
 import os
 
 

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/utils/specification.py
----------------------------------------------------------------------
diff --git a/aria/utils/specification.py b/aria/utils/specification.py
index e74c103..8c51134 100644
--- a/aria/utils/specification.py
+++ b/aria/utils/specification.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Utilities for cross-referencing code with specification documents.
+"""
+
 from .collections import OrderedDict
 
 

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/utils/threading.py
----------------------------------------------------------------------
diff --git a/aria/utils/threading.py b/aria/utils/threading.py
index bfd30f5..b9d627a 100644
--- a/aria/utils/threading.py
+++ b/aria/utils/threading.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Threading utilities.
+"""
+
 from __future__ import absolute_import  # so we can import standard 'threading'
 
 import sys
@@ -26,6 +30,7 @@ from .exceptions import print_exception
 class ExecutorException(Exception):
     pass
 
+
 class DaemonThread(Thread):
     def __init__(self, *args, **kwargs):
         super(DaemonThread, self).__init__(*args, **kwargs)
@@ -33,16 +38,15 @@ class DaemonThread(Thread):
 
     def run(self):
         """
-        We're overriding `Thread.run` in order to avoid annoying (but harmless) error
-        messages during shutdown. The problem is that CPython nullifies the
-        global state _before_ shutting down daemon threads, so that exceptions
-        might happen, and then `Thread.__bootstrap_inner` prints them out.
+        We're overriding ``Thread.run`` in order to avoid annoying (but harmless) error messages
+        during shutdown. The problem is that CPython nullifies the global state _before_ shutting
+        down daemon threads, so that exceptions might happen, and then ``Thread.__bootstrap_inner``
+        prints them out.
 
         Our solution is to swallow these exceptions here.
 
-        The side effect is that uncaught exceptions in our own thread code will _not_
-        be printed out as usual, so it's our responsibility to catch them in our
-        code.
+        The side effect is that uncaught exceptions in our own thread code will _not_ be printed out
+        as usual, so it's our responsibility to catch them in our code.
         """
 
         try:
@@ -54,6 +58,7 @@ class DaemonThread(Thread):
             # Exceptions might occur in daemon threads during interpreter shutdown
             pass
 
+
 # https://gist.github.com/tliron/81dd915166b0bfc64be08b4f8e22c835
 class FixedThreadPoolExecutor(object):
     """
@@ -77,8 +82,8 @@ class FixedThreadPoolExecutor(object):
         executor.raise_first()
         print executor.returns
 
-    You can also use it with the Python "with" keyword, in which case you don't need to call "close"
-    explicitly::
+    You can also use it with the Python ``with`` keyword, in which case you don't need to call
+    ``close`` explicitly::
 
         with FixedThreadPoolExecutor(10) as executor:
             for value in range(100):
@@ -95,11 +100,10 @@ class FixedThreadPoolExecutor(object):
                  timeout=None,
                  print_exceptions=False):
         """
-        :param size: Number of threads in the pool (fixed).
-        :param timeout: Timeout in seconds for all
-               blocking operations. (Defaults to none, meaning no timeout)
-        :param print_exceptions: Set to true in order to
-               print exceptions from tasks. (Defaults to false)
+        :param size: number of threads in the pool; if ``None`` will use an optimal number for the
+         platform
+        :param timeout: timeout in seconds for all blocking operations (``None`` means no timeout)
+        :param print_exceptions: set to ``True`` in order to print exceptions from tasks
         """
         if not size:
             try:
@@ -131,7 +135,7 @@ class FixedThreadPoolExecutor(object):
 
         The task will be called ASAP on the next available worker thread in the pool.
 
-        Will raise an :class:`ExecutorException` exception if cannot be submitted.
+        :raises ExecutorException: if cannot be submitted
         """
 
         try:
@@ -145,7 +149,7 @@ class FixedThreadPoolExecutor(object):
 
         You cannot submit tasks anymore after calling this.
 
-        This is called automatically upon exit if you are using the "with" keyword.
+        This is called automatically upon exit if you are using the ``with`` keyword.
         """
 
         self.drain()
@@ -194,9 +198,9 @@ class FixedThreadPoolExecutor(object):
         """
         If exceptions were thrown by any task, then the first one will be raised.
 
-        This is rather arbitrary: proper handling would involve iterating all the
-        exceptions. However, if you want to use the "raise" mechanism, you are
-        limited to raising only one of them.
+        This is rather arbitrary: proper handling would involve iterating all the exceptions.
+        However, if you want to use the "raise" mechanism, you are limited to raising only one of
+        them.
         """
 
         exceptions = self.exceptions
@@ -238,13 +242,13 @@ class FixedThreadPoolExecutor(object):
         self.close()
         return False
 
+
 class LockedList(list):
     """
-    A list that supports the "with" keyword with a built-in lock.
+    A list that supports the ``with`` keyword with a built-in lock.
 
-    Though Python lists are thread-safe in that they will not raise exceptions
-    during concurrent access, they do not guarantee atomicity. This class will
-    let you gain atomicity when needed.
+    Though Python lists are thread-safe in that they will not raise exceptions during concurrent
+    access, they do not guarantee atomicity. This class will let you gain atomicity when needed.
     """
 
     def __init__(self, *args, **kwargs):
@@ -260,7 +264,7 @@ class LockedList(list):
 
 class ExceptionThread(Thread):
     """
-    A thread from which top level exceptions can be retrieved or reraised
+    A thread from which top level exceptions can be retrieved or re-raised.
     """
     def __init__(self, *args, **kwargs):
         Thread.__init__(self, *args, **kwargs)

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/utils/type.py
----------------------------------------------------------------------
diff --git a/aria/utils/type.py b/aria/utils/type.py
index f08159a..fe88a62 100644
--- a/aria/utils/type.py
+++ b/aria/utils/type.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Type utilities.
+"""
+
 import datetime
 
 from .specification import implements_specification
@@ -79,7 +83,7 @@ def full_type_name(value):
 @implements_specification('3.2.1-1', 'tosca-simple-1.0')
 def canonical_type_name(value):
     """
-    Returns the canonical TOSCA type name of a primitive value, or None if unknown.
+    Returns the canonical TOSCA type name of a primitive value, or ``None`` if unknown.
 
     For a list of TOSCA type names, see the `TOSCA Simple Profile v1.0
     cos01 specification <http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.0/cos01
@@ -95,7 +99,7 @@ def canonical_type_name(value):
 @implements_specification('3.2.1-2', 'tosca-simple-1.0')
 def canonical_type(type_name):
     """
-    Return the canonical type for any Python, YAML, or TOSCA type name or alias, or None if
+    Return the canonical type for any Python, YAML, or TOSCA type name or alias, or ``None`` if
     unsupported.
 
     :param type_name: Type name (case insensitive)
@@ -109,9 +113,8 @@ def validate_value_type(value, type_name):
     Validate that a value is of a specific type. Supports Python, YAML, and TOSCA type names and
     aliases.
 
-    A ValueError will be raised on type mismatch.
-
-    :param type_name: Type name (case insensitive)
+    :param type_name: type name (case insensitive)
+    :raises ~exceptions.ValueError: on type mismatch
     """
 
     the_type = canonical_type(type_name)
@@ -132,9 +135,8 @@ def convert_value_to_type(str_value, python_type_name):
     """
     Converts a value to a specific Python primitive type.
 
-    A ValueError will be raised for unsupported types or conversion failure.
-
     :param python_type_name: Python primitive type name (case insensitive)
+    :raises ~exceptions.ValueError: for unsupported types or conversion failure
     """
 
     python_type_name = python_type_name.lower()

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/utils/uris.py
----------------------------------------------------------------------
diff --git a/aria/utils/uris.py b/aria/utils/uris.py
index 5f7bcf5..49881f2 100644
--- a/aria/utils/uris.py
+++ b/aria/utils/uris.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+URI utilities.
+"""
+
 import os
 import urlparse
 
@@ -22,8 +26,8 @@ _IS_WINDOWS = (os.name == 'nt')
 
 def as_file(uri):
     """
-    If the URI is a file (either the :code:`file` scheme or no scheme), then returns the normalized
-    path. Otherwise, returns None.
+    If the URI is a file (either the ``file`` scheme or no scheme), then returns the normalized
+    path. Otherwise, returns ``None``.
     """
 
     if _IS_WINDOWS:

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/utils/uuid.py
----------------------------------------------------------------------
diff --git a/aria/utils/uuid.py b/aria/utils/uuid.py
index 1f340c6..d6c9ced 100644
--- a/aria/utils/uuid.py
+++ b/aria/utils/uuid.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+UUID generation utilities.
+"""
+
 from __future__ import absolute_import  # so we can import standard 'uuid'
 
 from random import randrange
@@ -32,14 +36,14 @@ def generate_uuid(length=None, variant='base57'):
     """
     A random string with varying degrees of guarantee of universal uniqueness.
 
-    :param variant: options are:
-                    * 'base57' (the default) uses a mix of upper and lowercase alphanumerics
-                      ensuring no visually ambiguous characters; default length 22
-                    * 'alphanumeric' uses lowercase alphanumeric; default length 25
-                    * 'uuid' user lowercase hexadecimal in the classic UUID format, including
-                      dashes; length is always 36
-                    * 'hex' uses lowercase hexadecimal characters but has no guarantee of
-                      uniqueness; default length of 5
+    :param variant:
+     * ``base57`` (the default) uses a mix of upper and lowercase alphanumerics ensuring no visually
+       ambiguous characters; default length 22
+     * ``alphanumeric`` uses lowercase alphanumeric; default length 25
+     * ``uuid`` uses lowercase hexadecimal in the classic UUID format, including dashes; length is
+       always 36
+     * ``hex`` uses lowercase hexadecimal characters but has no guarantee of uniqueness; default
+       length of 5
     """
 
     if variant == 'base57':

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/utils/validation.py
----------------------------------------------------------------------
diff --git a/aria/utils/validation.py b/aria/utils/validation.py
index 193cb33..3452dcc 100644
--- a/aria/utils/validation.py
+++ b/aria/utils/validation.py
@@ -14,7 +14,7 @@
 # limitations under the License.
 
 """
-Contains validation related utilities
+Validation utilities.
 """
 
 from .formatting import string_list_as_string
@@ -22,7 +22,7 @@ from .formatting import string_list_as_string
 
 class ValidatorMixin(object):
     """
-    A mixin that should be added to classes that require validating user input
+    A mix0in that should be added to classes that require validating user input.
     """
 
     _ARGUMENT_TYPE_MESSAGE = '{name} argument must be {type} based, got {arg!r}'
@@ -68,7 +68,7 @@ class ValidatorMixin(object):
 def validate_function_arguments(func, func_kwargs):
     """
     Validates all required arguments are supplied to ``func`` and that no additional arguments are
-    supplied
+    supplied.
     """
 
     _kwargs_flags = 8

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/utils/versions.py
----------------------------------------------------------------------
diff --git a/aria/utils/versions.py b/aria/utils/versions.py
index 925f59e..521004c 100644
--- a/aria/utils/versions.py
+++ b/aria/utils/versions.py
@@ -14,7 +14,7 @@
 # limitations under the License.
 
 """
-General-purpose version string handling
+Verion string utilities.
 """
 
 import re
@@ -55,8 +55,9 @@ class VersionString(unicode):
     Any value that does not conform to this format will be treated as a zero version, which would
     be lesser than any non-zero version.
 
-    For efficient list sorts use the ``key`` property, e.g.:
-    ``sorted(versions, key=lambda x: x.key)``
+    For efficient list sorts use the ``key`` property, e.g.::
+
+        sorted(versions, key=lambda x: x.key)
     """
 
     NULL = None # initialized below
@@ -84,9 +85,9 @@ def parse_version_string(version): # pylint: disable=too-many-branches
     """
     Parses a version string.
 
-    :param version: The version string
-    :returns: The primary tuple and qualifier float
-    :rtype: ((int), float)
+    :param version: version string
+    :returns: primary tuple and qualifier float
+    :rtype: ((:obj:`int`), :obj:`float`)
     """
 
     if version is None:

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/docs/aria.cli.rst
----------------------------------------------------------------------
diff --git a/docs/aria.cli.rst b/docs/aria.cli.rst
new file mode 100644
index 0000000..c325cf0
--- /dev/null
+++ b/docs/aria.cli.rst
@@ -0,0 +1,100 @@
+..
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+   
+       http://www.apache.org/licenses/LICENSE-2.0
+   
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+:mod:`aria.cli`
+===============
+
+.. automodule:: aria.cli
+
+:mod:`aria.cli.color`
+---------------------
+
+.. automodule:: aria.cli.color
+
+:mod:`aria.cli.csar`
+--------------------
+
+.. automodule:: aria.cli.csar
+
+:mod:`aria.cli.defaults`
+------------------------
+
+.. automodule:: aria.cli.defaults
+
+:mod:`aria.cli.exceptions`
+--------------------------
+
+.. automodule:: aria.cli.exceptions
+
+:mod:`aria.cli.execution_logging`
+---------------------------------
+
+.. automodule:: aria.cli.execution_logging
+
+:mod:`aria.cli.helptexts`
+-------------------------
+
+.. automodule:: aria.cli.helptexts
+
+:mod:`aria.cli.inputs`
+----------------------
+
+.. automodule:: aria.cli.inputs
+
+:mod:`aria.cli.logger`
+----------------------
+
+.. automodule:: aria.cli.logger
+
+:mod:`aria.cli.main`
+--------------------
+
+.. automodule:: aria.cli.main
+
+:mod:`aria.cli.service_template_utils`
+--------------------------------------
+
+.. automodule:: aria.cli.service_template_utils
+
+:mod:`aria.cli.table`
+---------------------
+
+.. automodule:: aria.cli.table
+
+:mod:`aria.cli.utils`
+---------------------
+
+.. automodule:: aria.cli.utils
+
+:mod:`aria.cli.config`
+----------------------
+
+.. automodule:: aria.cli.config
+
+:mod:`aria.cli.config.config`
+-----------------------------
+
+.. automodule:: aria.cli.config.config
+
+:mod:`aria.cli.core`
+--------------------
+
+.. automodule:: aria.cli.core
+
+:mod:`aria.cli.core.aria`
+-------------------------
+
+.. automodule:: aria.cli.core.aria



Mime
View raw message