Adding documentation for all ndb modules. (googleapis#6265)

dhermes · web-flow · commit 9280c3649c4d · 2018-10-18T12:15:22.000-07:00
diff --git a/ndb/MIGRATION_NOTES.md b/ndb/MIGRATION_NOTES.md
@@ -31,7 +31,7 @@ The primary differences come from:
 ## Differences (between old and new implementations)
 
 - The "standard" exceptions from App Engine are no longer available. Instead,
-  we'll create "shims" for them in `google.cloud.ndb._exceptions` to match the
+  we'll create "shims" for them in `google.cloud.ndb.exceptions` to match the
   class names and emulate behavior.
 - There is no replacement for `google.appengine.api.namespace_manager` which is
   used to determine the default namespace when not passed in to `Key()`
diff --git a/ndb/docs/blobstore.rst b/ndb/docs/blobstore.rst
@@ -0,0 +1,9 @@
+#########
+Blobstore
+#########
+
+.. automodule:: google.cloud.ndb.blobstore
+    :members:
+    :inherited-members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/ndb/docs/conf.py b/ndb/docs/conf.py
@@ -34,6 +34,10 @@
 # If your documentation needs a minimal Sphinx version, state it here.
 #
 # needs_sphinx = '1.0'
+nitpicky = True
+nitpick_ignore = [
+    ("py:obj", "google.cloud.datastore._app_engine_key_pb2.Reference")
+]
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
diff --git a/ndb/docs/django-middleware.rst b/ndb/docs/django-middleware.rst
@@ -0,0 +1,9 @@
+#################
+Django Middleware
+#################
+
+.. automodule:: google.cloud.ndb.django_middleware
+    :members:
+    :inherited-members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/ndb/docs/exceptions.rst b/ndb/docs/exceptions.rst
@@ -0,0 +1,8 @@
+##########
+Exceptions
+##########
+
+.. automodule:: google.cloud.ndb.exceptions
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/ndb/docs/index.rst b/ndb/docs/index.rst
@@ -6,7 +6,16 @@
    :hidden:
    :maxdepth: 2
 
-   Key <key>
-   Model <model>
+   key
+   model
+   query
+   exceptions
+   polymodel
+   django-middleware
+   msgprop
+   blobstore
+   metadata
+   stats
 
-Placeholder.
+.. automodule:: google.cloud.ndb
+    :no-members:
diff --git a/ndb/docs/key.rst b/ndb/docs/key.rst
@@ -1,6 +1,6 @@
-###############################
-``google.cloud.ndb.key`` module
-###############################
+###
+Key
+###
 
 .. automodule:: google.cloud.ndb.key
     :members:
diff --git a/ndb/docs/metadata.rst b/ndb/docs/metadata.rst
@@ -0,0 +1,9 @@
+##################
+Datastore Metadata
+##################
+
+.. automodule:: google.cloud.ndb.metadata
+    :members:
+    :inherited-members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/ndb/docs/model.rst b/ndb/docs/model.rst
@@ -1,9 +1,9 @@
-#################################
-``google.cloud.ndb.model`` module
-#################################
+##################
+Model and Property
+##################
 
 .. automodule:: google.cloud.ndb.model
     :members:
-    :exclude-members: Key
+    :exclude-members: Key, Rollback
     :undoc-members:
     :show-inheritance:
diff --git a/ndb/docs/msgprop.rst b/ndb/docs/msgprop.rst
@@ -0,0 +1,9 @@
+###########################
+ProtoRPC Message Properties
+###########################
+
+.. automodule:: google.cloud.ndb.msgprop
+    :members:
+    :inherited-members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/ndb/docs/polymodel.rst b/ndb/docs/polymodel.rst
@@ -0,0 +1,9 @@
+##############################
+Polymorphic Models and Queries
+##############################
+
+.. automodule:: google.cloud.ndb.polymodel
+    :members:
+    :inherited-members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/ndb/docs/query.rst b/ndb/docs/query.rst
@@ -0,0 +1,9 @@
+#####
+Query
+#####
+
+.. automodule:: google.cloud.ndb.query
+    :members:
+    :inherited-members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/ndb/docs/stats.rst b/ndb/docs/stats.rst
@@ -0,0 +1,9 @@
+####################
+Datastore Statistics
+####################
+
+.. automodule:: google.cloud.ndb.stats
+    :members:
+    :inherited-members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/ndb/src/google/cloud/ndb/__init__.py b/ndb/src/google/cloud/ndb/__init__.py
@@ -16,9 +16,13 @@
 
 It was originally included in the Google App Engine runtime as a "new"
 version of the ``db`` API (hence ``ndb``).
+
+.. autodata:: __version__
+.. autodata:: __all__
 """
 
 __version__ = "0.0.1.dev1"
+"""Current ``ndb`` version."""
 __all__ = [
     "AutoBatcher",
     "Context",
@@ -115,6 +119,7 @@
     "tasklet",
     "toplevel",
 ]
+"""All top-level exported names."""
 
 from google.cloud.ndb.context import AutoBatcher
 from google.cloud.ndb.context import Context
diff --git a/ndb/src/google/cloud/ndb/exceptions.py b/ndb/src/google/cloud/ndb/exceptions.py
@@ -20,7 +20,7 @@
 """
 
 
-__all__ = []
+__all__ = ["Error", "BadValueError", "BadArgumentError", "Rollback"]
 
 
 class Error(Exception):
diff --git a/ndb/src/google/cloud/ndb/key.py b/ndb/src/google/cloud/ndb/key.py
@@ -92,7 +92,7 @@
 from google.cloud.datastore import key as _key_module
 import google.cloud.datastore
 
-from google.cloud.ndb import _exceptions
+from google.cloud.ndb import exceptions
 
 
 __all__ = ["Key"]
@@ -1075,7 +1075,7 @@ def _parse_from_args(
     else:
         project = _project_from_app(app, allow_empty=True)
         if not isinstance(parent, Key):
-            raise _exceptions.BadValueError(
+            raise exceptions.BadValueError(
                 "Expected Key instance, got {!r}".format(parent)
             )
         # Offload verification of parent to ``google.cloud.datastore.Key()``.
@@ -1163,7 +1163,7 @@ def _clean_flat_path(flat):
         id_ = flat[i + 1]
         if id_ is None:
             if i + 2 < len(flat):
-                raise _exceptions.BadArgumentError(
+                raise exceptions.BadArgumentError(
                     "Incomplete Key entry must be last"
                 )
         elif not isinstance(id_, (str, int)):
diff --git a/ndb/src/google/cloud/ndb/model.py b/ndb/src/google/cloud/ndb/model.py
@@ -15,7 +15,7 @@
 """Model classes for datastore objects and properties for models."""
 
 
-from google.cloud.ndb import _exceptions
+from google.cloud.ndb import exceptions
 from google.cloud.ndb import key as key_module
 
 
@@ -81,17 +81,17 @@
 Key = key_module.Key
 BlobKey = NotImplemented  # From `google.appengine.api.datastore_types`
 GeoPt = NotImplemented  # From `google.appengine.api.datastore_types`
-Rollback = _exceptions.Rollback
+Rollback = exceptions.Rollback
 
 
-class KindError(_exceptions.BadValueError):
+class KindError(exceptions.BadValueError):
     """Raised when an implementation for a kind can't be found.
 
     May also be raised when the kind is not a byte string.
     """
 
 
-class InvalidPropertyError(_exceptions.Error):
+class InvalidPropertyError(exceptions.Error):
     """Raised when a property is not applicable to a given use.
 
     For example, a property must exist and be indexed to be used in a query's
@@ -103,11 +103,11 @@ class InvalidPropertyError(_exceptions.Error):
 """This alias for :class:`InvalidPropertyError` is for legacy support."""
 
 
-class UnprojectedPropertyError(_exceptions.Error):
+class UnprojectedPropertyError(exceptions.Error):
     """Raised when getting a property value that's not in the projection."""
 
 
-class ReadonlyPropertyError(_exceptions.Error):
+class ReadonlyPropertyError(exceptions.Error):
     """Raised when attempting to set a property value that is read-only."""
 
 
@@ -268,7 +268,7 @@ def make_connection(*args, **kwargs):
 
 
 class ModelAttribute:
-    """Base for :meth:`_fix_up` implementing classes."""
+    """Base for classes that implement a ``_fix_up()`` method."""
 
     def _fix_up(self, cls, code_name):
         """Fix-up property name. To be implemented by subclasses.
diff --git a/ndb/src/google/cloud/ndb/query.py b/ndb/src/google/cloud/ndb/query.py
@@ -14,7 +14,7 @@
 
 """High-level wrapper for datastore queries."""
 
-from google.cloud.ndb import _exceptions
+from google.cloud.ndb import exceptions
 
 
 __all__ = [
@@ -71,7 +71,7 @@ class Parameter(ParameterizedThing):
     ``Parameter(1)`` corresponds to a slot labeled ``:1`` in a GQL query.
     ``Parameter('xyz')`` corresponds to a slot labeled ``:xyz``.
 
-    The value must be set (bound) separately by calling :meth:`set`.
+    The value must be set (bound) separately.
 
     Args:
         key (Union[str, int]): The parameter key.
@@ -120,7 +120,7 @@ def resolve(self, bindings, used):
         """
         key = self._key
         if key not in bindings:
-            raise _exceptions.BadArgumentError(
+            raise exceptions.BadArgumentError(
                 "Parameter :{} is not bound.".format(key)
             )
         value = bindings[key]
diff --git a/ndb/tests/unit/test_key.py b/ndb/tests/unit/test_key.py
@@ -20,7 +20,7 @@
 import google.cloud.datastore
 import pytest
 
-from google.cloud.ndb import _exceptions
+from google.cloud.ndb import exceptions
 from google.cloud.ndb import key as key_module
 from google.cloud.ndb import model
 import tests.unit.utils
@@ -66,7 +66,7 @@ def test_constructor_partial():
     def test_constructor_invalid_id_type():
         with pytest.raises(TypeError):
             key_module.Key("Kind", object())
-        with pytest.raises(_exceptions.BadArgumentError):
+        with pytest.raises(exceptions.BadArgumentError):
             key_module.Key("Kind", None, "Also", 10)
 
     @staticmethod
@@ -186,7 +186,7 @@ def test_constructor_with_parent(self):
 
     def test_constructor_with_parent_bad_type(self):
         parent = unittest.mock.sentinel.parent
-        with pytest.raises(_exceptions.BadValueError):
+        with pytest.raises(exceptions.BadValueError):
             key_module.Key("Zip", 10, parent=parent)
 
     @staticmethod
diff --git a/ndb/tests/unit/test_query.py b/ndb/tests/unit/test_query.py
@@ -16,7 +16,7 @@
 
 import pytest
 
-from google.cloud.ndb import _exceptions
+from google.cloud.ndb import exceptions
 from google.cloud.ndb import query
 import tests.unit.utils
 
@@ -111,7 +111,7 @@ def test_resolve():
     def test_resolve_missing_key():
         parameter = query.Parameter(9000)
         used = {}
-        with pytest.raises(_exceptions.BadArgumentError):
+        with pytest.raises(exceptions.BadArgumentError):
             parameter.resolve({}, used)
 
         assert used == {}
