Improve docstrings for Sphinx output

Also remove package and module names from classes and functions.

Also remove stix2.base from docs. We hide all private classes and
functions from the docs, so the only thing the documentation for base
included was STIXJSONEncoder.

docs/api/stix2.base.rst

@@ -1,5 +0,0 @@
-base
-==========
-
-.. automodule:: stix2.base
-   :members:

docs/conf.py

@@ -19,6 +19,7 @@ autodoc_member_order = 'groupwise'
 autosummary_generate = True
 napoleon_numpy_docstring = False  # Force consistency, leave only Google
 napoleon_use_rtype = False
+add_module_names = False
 
 templates_path = ['_templates']
 source_suffix = '.rst'

stix2/__init__.py

@@ -3,7 +3,6 @@
 .. autosummary::
    :toctree: api
 
-   base
    common
    core
    environment

stix2/common.py

@@ -65,7 +65,7 @@ class StatementMarking(_STIXBase):
 
 
 class MarkingProperty(Property):
-    """Represent the marking objects in the `definition` property of
+    """Represent the marking objects in the ``definition`` property of
     marking-definition objects.
     """
 
@@ -120,17 +120,15 @@ def _register_marking(cls):
 
 
 def CustomMarking(type='x-custom-marking', properties=None):
-    """
-    Custom STIX Marking decorator.
+    """Custom STIX Marking decorator.
 
-    Examples:
-
-        @CustomMarking('x-custom-marking', [
-            ('property1', StringProperty(required=True)),
-            ('property2', IntegerProperty()),
-        ])
-        class MyNewMarkingObjectType():
-            pass
+    Example:
+        >>> @CustomMarking('x-custom-marking', [
+        ...     ('property1', StringProperty(required=True)),
+        ...     ('property2', IntegerProperty()),
+        ... ])
+        ... class MyNewMarkingObjectType():
+        ...     pass
 
     """
     def custom_builder(cls):

stix2/core.py

@@ -1,4 +1,4 @@
-"""STIX 2.0 Objects that are neither SDOs nor SROs"""
+"""STIX 2.0 Objects that are neither SDOs nor SROs."""
 
 from collections import OrderedDict
 

stix2/exceptions.py

@@ -3,7 +3,7 @@ class STIXError(Exception):
 
 
 class InvalidValueError(STIXError, ValueError):
-    """An invalid value was provided to a STIX object's __init__."""
+    """An invalid value was provided to a STIX object's ``__init__``."""
 
     def __init__(self, cls, prop_name, reason):
         super(InvalidValueError, self).__init__()
@@ -45,7 +45,7 @@ class ExtraPropertiesError(STIXError, TypeError):
 
 
 class ImmutableError(STIXError, ValueError):
-    """Attempted to modify an object after creation"""
+    """Attempted to modify an object after creation."""
 
     def __init__(self, cls, key):
         super(ImmutableError, self).__init__()
@@ -85,7 +85,7 @@ class InvalidObjRefError(STIXError, ValueError):
 
 
 class UnmodifiablePropertyError(STIXError, ValueError):
-    """Attempted to modify an unmodifiable property of object when creating a new version"""
+    """Attempted to modify an unmodifiable property of object when creating a new version."""
 
     def __init__(self, unchangable_properties):
         super(UnmodifiablePropertyError, self).__init__()
@@ -139,7 +139,7 @@ class AtLeastOnePropertyError(STIXError, TypeError):
 
 
 class RevokeError(STIXError, ValueError):
-    """Attempted to an operation on a revoked object"""
+    """Attempted to an operation on a revoked object."""
 
     def __init__(self, called_by):
         super(RevokeError, self).__init__()
@@ -153,7 +153,7 @@ class RevokeError(STIXError, ValueError):
 
 
 class ParseError(STIXError, ValueError):
-    """Could not parse object"""
+    """Could not parse object."""
 
     def __init__(self, msg):
         super(ParseError, self).__init__(msg)

stix2/markings/granular_markings.py

@@ -1,3 +1,5 @@
+"""Functions for working with STIX 2.0 granular markings.
+"""
 
 from stix2 import exceptions
 from stix2.markings import utils

stix2/markings/object_markings.py

@@ -1,3 +1,5 @@
+"""Functions for working with STIX 2.0 object markings.
+"""
 
 from stix2 import exceptions
 from stix2.markings import utils

stix2/markings/utils.py

@@ -1,3 +1,5 @@
+"""Utility functions for STIX 2.0 data markings.
+"""
 
 import collections
 

stix2/observables.py

@@ -1,8 +1,8 @@
-"""STIX 2.0 Cyber Observable Objects
+"""STIX 2.0 Cyber Observable Objects.
 
 Embedded observable object types, such as Email MIME Component, which is
-embedded in Email Message objects, inherit from _STIXBase instead of Observable
-and do not have a '_type' attribute.
+embedded in Email Message objects, inherit from ``_STIXBase`` instead of
+Observable and do not have a ``_type`` attribute.
 """
 
 from collections import OrderedDict
@@ -19,6 +19,8 @@ from .utils import get_dict
 
 
 class ObservableProperty(Property):
+    """Property for holding Cyber Observable Objects.
+    """
 
     def clean(self, value):
         try:
@@ -39,7 +41,7 @@ class ObservableProperty(Property):
 
 
 class ExtensionsProperty(DictionaryProperty):
-    """ Property for representing extensions on Observable objects
+    """Property for representing extensions on Observable objects.
     """
 
     def __init__(self, enclosing_type=None, required=False):
@@ -138,7 +140,6 @@ class EmailAddress(_Observable):
         ('display_name', StringProperty()),
         ('belongs_to_ref', ObjectReferenceProperty(valid_types='user-account')),
         ('extensions', ExtensionsProperty(enclosing_type=_type)),
-
     ])
 
 
@@ -798,16 +799,15 @@ def _register_observable(new_observable):
 
 
 def CustomObservable(type='x-custom-observable', properties=None):
-    """Custom STIX Cyber Observable type decorator
+    """Custom STIX Cyber Observable Object type decorator.
 
-    Example 1:
-
-    @CustomObservable('x-custom-observable', [
-        ('property1', StringProperty(required=True)),
-        ('property2', IntegerProperty()),
-    ])
-    class MyNewObservableType():
-        pass
+    Example:
+        >>> @CustomObservable('x-custom-observable', [
+        ...     ('property1', StringProperty(required=True)),
+        ...     ('property2', IntegerProperty()),
+        ... ])
+        ... class MyNewObservableType():
+        ...     pass
     """
 
     def custom_builder(cls):
@@ -873,7 +873,7 @@ def _register_extension(observable, new_extension):
 
 
 def CustomExtension(observable=None, type='x-custom-observable', properties={}):
-    """Decorator for custom extensions to STIX Cyber Observables
+    """Decorator for custom extensions to STIX Cyber Observables.
     """
 
     if not observable or not issubclass(observable, _Observable):

stix2/properties.py

@@ -19,43 +19,44 @@ class Property(object):
     """Represent a property of STIX data type.
 
     Subclasses can define the following attributes as keyword arguments to
-    __init__():
+    ``__init__()``.
 
-    - `required` - If `True`, the property must be provided when creating an
-        object with that property. No default value exists for these properties.
-        (Default: `False`)
-    - `fixed` - This provides a constant default value. Users are free to
-        provide this value explicity when constructing an object (which allows
-        you to copy *all* values from an existing object to a new object), but
-        if the user provides a value other than the `fixed` value, it will raise
-        an error. This is semantically equivalent to defining both:
-        - a `clean()` function that checks if the value matches the fixed
-          value, and
-        - a `default()` function that returns the fixed value.
-        (Default: `None`)
+    Args:
+        required (bool): If ``True``, the property must be provided when creating an
+            object with that property. No default value exists for these properties.
+            (Default: ``False``)
+        fixed: This provides a constant default value. Users are free to
+            provide this value explicity when constructing an object (which allows
+            you to copy **all** values from an existing object to a new object), but
+            if the user provides a value other than the ``fixed`` value, it will raise
+            an error. This is semantically equivalent to defining both:
 
-    Subclasses can also define the following functions.
+            - a ``clean()`` function that checks if the value matches the fixed
+              value, and
+            - a ``default()`` function that returns the fixed value.
 
-    - `def clean(self, value) -> any:`
-        - Return a value that is valid for this property. If `value` is not
+    Subclasses can also define the following functions:
+
+    - ``def clean(self, value) -> any:``
+        - Return a value that is valid for this property. If ``value`` is not
           valid for this property, this will attempt to transform it first. If
-          `value` is not valid and no such transformation is possible, it should
+          ``value`` is not valid and no such transformation is possible, it should
           raise a ValueError.
-    - `def default(self):`
+    - ``def default(self):``
         - provide a default value for this property.
-        - `default()` can return the special value `NOW` to use the current
+        - ``default()`` can return the special value ``NOW`` to use the current
             time. This is useful when several timestamps in the same object need
             to use the same default value, so calling now() for each property--
             likely several microseconds apart-- does not work.
 
-    Subclasses can instead provide a lambda function for `default` as a keyword
-    argument. `clean` should not be provided as a lambda since lambdas cannot
+    Subclasses can instead provide a lambda function for ``default`` as a keyword
+    argument. ``clean`` should not be provided as a lambda since lambdas cannot
     raise their own exceptions.
 
-    When instantiating Properties, `required` and `default` should not be used
-    together. `default` implies that the property is required in the specification
+    When instantiating Properties, ``required`` and ``default`` should not be used
+    together. ``default`` implies that the property is required in the specification
     so this function will be used to supply a value if none is provided.
-    `required` means that the user must provide this; it is required in the
+    ``required`` means that the user must provide this; it is required in the
     specification and we can't or don't want to create a default value.
     """
 
@@ -88,7 +89,7 @@ class ListProperty(Property):
 
     def __init__(self, contained, **kwargs):
         """
-        Contained should be a function which returns an object from the value.
+        ``contained`` should be a function which returns an object from the value.
         """
         if inspect.isclass(contained) and issubclass(contained, Property):
             # If it's a class and not an instance, instantiate it so that

stix2/sdo.py

@@ -298,8 +298,8 @@ def CustomObject(type='x-custom-type', properties=None):
         ... class MyNewObjectType():
         ...     pass
 
-    Supply an __init__() function to add any special validations to the custom
-    type. Don't call super().__init__() though - doing so will cause an error.
+    Supply an ``__init__()`` function to add any special validations to the custom
+    type. Don't call ``super().__init__()`` though - doing so will cause an error.
 
     Example:
         >>> @CustomObject('x-type-name', [