Merge pull request #206 from dhermes/tox-docstring-fix

Sphinx and PEP8 docstring fix

docs/conf.py

@@ -69,7 +69,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build']
+exclude_patterns = ['_build', '_components/*']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None

docs/index.rst

@@ -3,9 +3,15 @@
 .. toctree::
   :hidden:
 
+  common-api
   datastore-api
+  datastore-getting-started
+  datastore-quickstart
+  getting-started
   storage-api
-  common-api
+  storage-getting-started
+  storage-quickstart
+
 
 Google Cloud Python API
 =======================

gcloud/datastore/__init__.py

@@ -71,7 +71,10 @@ def get_connection(client_email, private_key_path):
 
 
 def get_dataset(dataset_id, client_email, private_key_path):
-  """Shortcut method to establish a connection to a particular dataset in the Cloud Datastore.
+  """Establish a connection to a particular dataset in the Cloud Datastore.
+
+  This is a shortcut method for creating a connection and using it
+  to connect to a dataset.
 
   You'll generally use this as the first call to working with the API:
 

gcloud/datastore/entity.py

@@ -70,7 +70,7 @@ def __init__(self, dataset=None, kind=None):
             self._key = None
 
     def dataset(self):
-        """Get the :class:`gcloud.datastore.dataset.Dataset` in which this entity belongs.
+        """Get the :class:`.dataset.Dataset` in which this entity belongs.
 
         :rtype: :class:`gcloud.datastore.dataset.Dataset`
         :returns: The Dataset containing the entity if there is a key,
@@ -86,7 +86,7 @@ def dataset(self):
             return self.key().dataset()
 
     def key(self, key=None):
-        """Get or set the :class:`gcloud.datastore.key.Key` on the current entity.
+        """Get or set the :class:`.datastore.key.Key` on the current entity.
 
         :type key: :class:`glcouddatastore.key.Key`
         :param key: The key you want to set on the entity.
@@ -122,7 +122,10 @@ def kind(self):
 
     @classmethod
     def from_key(cls, key):
-        """Factory method for creating an entity based on the :class:`gcloud.datastore.key.Key`.
+        """Create entity based on :class:`.datastore.key.Key`.
+
+        .. note::
+          This is a factory method.
 
         :type key: :class:`gcloud.datastore.key.Key`
         :param key: The key for the entity.

gcloud/datastore/key.py

@@ -8,6 +8,8 @@
 class Key(object):
   """
   An immutable representation of a datastore Key.
+
+  .. automethod:: __init__
   """
 
   def __init__(self, dataset=None, namespace=None, path=None):
@@ -52,7 +54,7 @@ def from_protobuf(cls, pb, dataset=None):
 
     :type dataset: :class:`gcloud.datastore.dataset.Dataset`
     :param dataset: A dataset instance.  If not passed, defaults to an
-    instance whose ID is derived from pb.
+                    instance whose ID is derived from pb.
 
     :rtype: :class:`gcloud.datastore.key.Key`
     :returns: a new `Key` instance
@@ -116,17 +118,18 @@ def to_protobuf(self):
   def from_path(cls, *args, **kwargs):
     """Factory method for creating a key based on a path.
 
-    :type args: :class:`tuple
-    :param args: sequence of even length, where the first of each
-    pair is a string representing the 'kind' of the path element, and the
-    second of the pair is either a string (for the path element's name)
-    or an integer (for its id).
+    :type args: :class:`tuple`
+    :param args: sequence of even length, where the first of each pair is a
+                 string representing the 'kind' of the path element, and the
+                 second of the pair is either a string (for the path
+                 element's name) or an integer (for its id).
 
     :type kwargs: :class:`dict`
-    :param kwargs: Other named parameters which can be passed to `__init__()`.
+    :param kwargs: Other named parameters which can be passed to
+                   :func:`Key.__init__`.
 
     :rtype: :class:`gcloud.datastore.key.Key`
-    :returns: a new `Key` instance
+    :returns: a new :class:`Key` instance
     """
     if len(args) % 2:
         raise ValueError('Must pass an even number of args.')
@@ -150,7 +153,7 @@ def is_partial(self):
 
     :rtype: :class:`bool`
     :returns: True if the last element of the key's path does not have an 'id'
-    or a 'name'.
+              or a 'name'.
     """
     return (self.id_or_name() is None)
 
@@ -194,11 +197,11 @@ def path(self, path=None):
 
     :type path: sequence of dicts
     :param path: Each dict must have keys 'kind' (a string) and optionally
-    'name' (a string) or 'id' (an integer).
+                 'name' (a string) or 'id' (an integer).
 
     :rtype: :class:`Key` (for setter); or :class:`str` (for getter)
     :returns: a new key, cloned from self., with the given path (setter);
-             or self's path (getter).
+              or self's path (getter).
     """
     if path:
       clone = self._clone()
@@ -263,7 +266,7 @@ def id_or_name(self):
 
     :rtype: :class:`int` (if 'id' is set); or :class:`str` (the 'name')
     :returns: True if the last element of the key's path has either an 'id'
-    or a 'name'.
+              or a 'name'.
     """
     return self.id() or self.name()
 
@@ -272,7 +275,8 @@ def parent(self):  # pragma NO COVER
 
     :rtype: :class:`gcloud.datastore.key.Key`
     :returns: a new `Key` instance, whose path consists of all but the last
-    element of self's path.  If self has only one path element, return None.
+              element of self's path.  If self has only one path element,
+              return None.
     """
     if len(self._path) <= 1:
         return None

gcloud/datastore/query.py

@@ -63,9 +63,9 @@ def _clone(self):
     return clone
 
   def to_protobuf(self):
-    """Convert the :class:`Query` instance to a :class:`gcloud.datastore.datastore_v1_pb2.Query`.
+    """Convert :class:`Query` instance to :class:`.datastore_v1_pb2.Query`.
 
-    :rtype: :class:`gclouddatstore.datastore_v1_pb2.Query`
+    :rtype: :class:`gcloud.datastore.datastore_v1_pb2.Query`
     :returns: A Query protobuf that can be sent to the protobuf API.
     """
     return self._pb
@@ -148,7 +148,7 @@ def ancestor(self, ancestor):
       >>> query = dataset.query('Person')
       >>> filtered_query = query.ancestor(['Person', '1'])
 
-    Each call to ``.ancestor()`` returns a cloned :class:`Query:,
+    Each call to ``.ancestor()`` returns a cloned :class:`Query`,
     however a query may only have one ancestor at a time.
 
     :type ancestor: :class:`gcloud.datastore.key.Key` or list

gcloud/storage/acl.py

@@ -379,7 +379,7 @@ def save(self):
 
 
 class DefaultObjectACL(BucketACL):
-  """A subclass of BucketACL representing the default object ACL for a bucket."""
+  """A class representing the default object ACL for a bucket."""
 
   def save(self):
     """Save this ACL as the default object ACL for the current bucket."""

gcloud/storage/bucket.py

@@ -104,7 +104,7 @@ def get_all_keys(self):
     return list(self)
 
   def new_key(self, key):
-    """Given a path name (or a Key), return a :class:`gcloud.storage.key.Key` object.
+    """Given a path name (or Key), return a :class:`.storage.key.Key` object.
 
     This is really useful when you're not sure
     if you have a Key object or a string path name.

gcloud/storage/iterator.py

@@ -146,7 +146,7 @@ def __init__(self, connection):
     super(BucketIterator, self).__init__(connection=connection, path='/b')
 
   def get_items_from_response(self, response):
-    """Factory method which yields :class:`gcloud.storage.bucket.Bucket` items from a response.
+    """Factory method which yields :class:`.Bucket` items from a response.
 
     :type response: dict
     :param response: The JSON API response for a page of buckets.
@@ -174,7 +174,7 @@ def __init__(self, bucket):
         connection=bucket.connection, path=bucket.path + '/o')
 
   def get_items_from_response(self, response):
-    """Factory method which yields :class:`gcloud.storage.key.Key` items from a response.
+    """Factory method, yields :class:`.storage.key.Key` items from response.
 
     :type response: dict
     :param response: The JSON API response for a page of keys.