Add datastore.__init__ to docs.

dhermes · dhermes · commit 6ce14440260e · 2016-10-31T22:55:08.000-07:00
This in turn required a fix in verify_included_modules to
turn `__init__.py` files into the correct module / package
name.
diff --git a/datastore/google/cloud/datastore/__init__.py b/datastore/google/cloud/datastore/__init__.py
@@ -14,38 +14,40 @@
 
 """Shortcut methods for getting set up with Google Cloud Datastore.
 
-You'll typically use these to get started with the API::
+You'll typically use these to get started with the API:
 
-    >>> from google.cloud import datastore
-    >>>
-    >>> client = datastore.Client()
-    >>> key = client.key('EntityKind', 1234)
-    >>> entity = datastore.Entity(key)
-    >>> query = client.query(kind='EntityKind')
+.. code-block:: python
+
+  from google.cloud import datastore
+
+  client = datastore.Client()
+  key = client.key('EntityKind', 1234)
+  entity = datastore.Entity(key)
+  query = client.query(kind='EntityKind')
 
 The main concepts with this API are:
 
-- :class:`google.cloud.datastore.connection.Connection`
+- :class:`~google.cloud.datastore.connection.Connection`
   which represents a connection between your machine and the Cloud Datastore
   API.
 
-- :class:`google.cloud.datastore.client.Client`
+- :class:`~google.cloud.datastore.client.Client`
   which represents a project (string) and namespace (string) bundled with
   a connection and has convenience methods for constructing objects with that
   project / namespace.
 
-- :class:`google.cloud.datastore.entity.Entity`
+- :class:`~google.cloud.datastore.entity.Entity`
   which represents a single entity in the datastore
   (akin to a row in relational database world).
 
-- :class:`google.cloud.datastore.key.Key`
+- :class:`~google.cloud.datastore.key.Key`
   which represents a pointer to a particular entity in the datastore
   (akin to a unique identifier in relational database world).
 
-- :class:`google.cloud.datastore.query.Query`
+- :class:`~google.cloud.datastore.query.Query`
   which represents a lookup or search over the rows in the datastore.
 
-- :class:`google.cloud.datastore.transaction.Transaction`
+- :class:`~google.cloud.datastore.transaction.Transaction`
   which represents an all-or-none transaction and enables consistency
   when race conditions may occur.
 """
diff --git a/docs/datastore-usage.rst b/docs/datastore-usage.rst
@@ -0,0 +1,6 @@
+Using the API
+=============
+
+.. automodule:: google.cloud.datastore
+  :members:
+  :show-inheritance:
diff --git a/docs/index.rst b/docs/index.rst
@@ -14,6 +14,7 @@
   :hidden:
   :caption: Datastore
 
+  datastore-usage
   Client <datastore-client>
   datastore-entities
   datastore-keys
diff --git a/scripts/verify_included_modules.py b/scripts/verify_included_modules.py
@@ -30,30 +30,29 @@
 DOCS_DIR = os.path.join(PROJECT_ROOT, 'docs')
 IGNORED_PREFIXES = ('test_', '_')
 IGNORED_MODULES = frozenset([
-    'google.cloud.__init__',
-    'google.cloud.bigquery.__init__',
-    'google.cloud.bigtable.__init__',
-    'google.cloud.datastore.__init__',
-    'google.cloud.dns.__init__',
-    'google.cloud.error_reporting.__init__',
-    'google.cloud.language.__init__',
-    'google.cloud.logging.__init__',
-    'google.cloud.logging.handlers.__init__',
-    'google.cloud.logging.handlers.transports.__init__',
-    'google.cloud.monitoring.__init__',
-    'google.cloud.pubsub.__init__',
-    'google.cloud.resource_manager.__init__',
-    'google.cloud.speech.__init__',
-    'google.cloud.storage.__init__',
-    'google.cloud.streaming.__init__',
+    'google.cloud',
+    'google.cloud.bigquery',
+    'google.cloud.bigtable',
+    'google.cloud.dns',
+    'google.cloud.error_reporting',
+    'google.cloud.language',
+    'google.cloud.logging',
+    'google.cloud.logging.handlers',
+    'google.cloud.logging.handlers.transports',
+    'google.cloud.monitoring',
+    'google.cloud.pubsub',
+    'google.cloud.resource_manager',
+    'google.cloud.speech',
+    'google.cloud.storage',
+    'google.cloud.streaming',
     'google.cloud.streaming.buffered_stream',
     'google.cloud.streaming.exceptions',
     'google.cloud.streaming.http_wrapper',
     'google.cloud.streaming.stream_slice',
     'google.cloud.streaming.transfer',
     'google.cloud.streaming.util',
-    'google.cloud.translate.__init__',
-    'google.cloud.vision.__init__',
+    'google.cloud.translate',
+    'google.cloud.vision',
     'google.cloud.vision.fixtures',
 ])
 PACKAGES = (
@@ -131,7 +130,11 @@ def get_public_modules(path, base_package=None):
                 if base_package is not None:
                     rel_path = os.path.join(base_package, rel_path)
                 # Turn into a Python module rather than a file path.
-                result.append(rel_path.replace(os.path.sep, '.'))
+                rel_path = rel_path.replace(os.path.sep, '.')
+                if mod_name == '__init__':
+                    result.append(rel_path[:-len('.__init__')])
+                else:
+                    result.append(rel_path)
 
     return result
 
