add spellcheck sphinx extension to docs build process (googleapis#123)

* add spellcheck sphinx extension to docs build process and kokoro

.kokoro/build.sh

@@ -14,6 +14,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+# Need enchant for spell check
+sudo apt-get update
+sudo apt-get -y install dictionaries-common aspell aspell-en \
+	                hunspell-en-us libenchant1c2a enchant
+
 set -eo pipefail
 
 cd github/python-ndb

docs/conf.py

@@ -17,6 +17,7 @@
 # sys.path.insert(0, os.path.abspath('.'))
 
 import google.cloud.ndb  # ``ndb`` must be installed to build the docs.
+import sphinxcontrib.spelling.filters
 
 # -- Project information -----------------------------------------------------
 
@@ -67,6 +68,7 @@
     "sphinx.ext.coverage",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
+    "sphinxcontrib.spelling",
 ]
 
 # autodoc/autosummary flags
@@ -232,3 +234,7 @@
 napoleon_use_ivar = False
 napoleon_use_param = True
 napoleon_use_rtype = True
+
+# spellcheck settings
+spelling_word_list_filename = "spelling_wordlist.txt"
+spelling_filters = [sphinxcontrib.spelling.filters.ContractionFilter]

docs/spelling_wordlist.txt

@@ -0,0 +1,94 @@
+Admin
+api
+App
+app
+Appengine
+appengine
+Args
+args
+auth
+backend
+Blobstore
+blobstore
+bool
+boolean
+builtin
+composable
+Datastore
+datastore
+deserialized
+Dict
+Django
+Expando
+expando
+fallback
+Firestore
+func
+google
+gRPC
+gql
+gVisor
+indices
+instantiation
+iter
+iterable
+lookups
+marshalling
+memcache
+Metaclass
+metaclass
+Metaclasses
+metaclasses
+Metadata
+metadata
+meth
+middleware
+MultiFuture
+multitenancy
+Namespace
+Namespaces
+namespace
+namespaces
+NDB
+ndb
+NoLongerImplementedError
+OAuth
+offline
+param
+polymorphism
+Pre
+pre
+prefetch
+protobuf
+proxied
+QueryOptions
+RequestHandler
+runtime
+schemas
+stackable
+subattribute
+subclassed
+subclasses
+subclassing
+subentities
+subentity
+subproperties
+subproperty
+superset
+Tasklet
+tasklet
+Tasklets
+tasklets
+timestamp
+Transactionally
+unary
+unicode
+unindexed
+unpickled
+unpickling
+urlsafe
+username
+UTF
+webapp
+websafe
+validator

noxfile.py

@@ -109,6 +109,7 @@ def blacken(session):
 def docs(session):
     # Install all dependencies.
     session.install("Sphinx")
+    session.install("sphinxcontrib.spelling")
     session.install(".")
     # Building the docs.
     run_args = ["bash", "test_utils/test_utils/scripts/update_docs.sh"]
@@ -119,6 +120,7 @@ def docs(session):
 def doctest(session):
     # Install all dependencies.
     session.install("Sphinx")
+    session.install("sphinxcontrib.spelling")
     session.install(".")
     # Run the script for building docs and running doctests.
     run_args = [

src/google/cloud/ndb/context.py

@@ -320,7 +320,7 @@ def set_memcache_timeout_policy(self, policy):
                 :class:`~google.cloud.ndb.key.Key` instance as a single
                 positional argument and returns an ``int`` indicating the
                 timeout, in seconds, for the key. ``0`` implies the default
-                timout. May be :data:`None`.
+                timeout. May be :data:`None`.
         """
         raise NotImplementedError
 

src/google/cloud/ndb/key.py

@@ -175,7 +175,7 @@ class Key:
         >>> ndb.Key(kind2, id2, parent=parent)
         Key('Parent', 'C', 'Child', 42)
 
-    You can also construct a Key from a "url-safe" encoded string:
+    You can also construct a Key from a "urlsafe" encoded string:
 
     .. doctest:: key-constructor-urlsafe
 
@@ -219,7 +219,7 @@ class Key:
         >>> ndb.Key(kwargs)
         Key('Cheese', 'Cheddar', namespace='good')
 
-    The "url-safe" string is really a websafe-base64-encoded serialized
+    The "urlsafe" string is really a websafe-base64-encoded serialized
     ``Reference``, but it's best to think of it as just an opaque unique
     string.
 

src/google/cloud/ndb/model.py

@@ -45,7 +45,7 @@ class Person(Model):
     person = Person(name='Arthur Dent', age=42)
     key = person.put()
 
-The return value from put() is a Key (see the documentation for ndb/key.py),
+The return value from put() is a Key (see the documentation for ``ndb/key.py``),
 which can be used to retrieve the same entity later::
 
     person2 = key.get()
@@ -1900,7 +1900,7 @@ def _validate_key(value, entity=None):
 class ModelKey(Property):
     """Special property to store a special "key" for a :class:`Model`.
 
-    This is intended to be used as a psuedo-:class:`Property` on each
+    This is intended to be used as a pseudo-:class:`Property` on each
     :class:`Model` subclass. It is **not** intended for other usage in
     application code.
 
@@ -2777,7 +2777,7 @@ def user_id(self):
 
         Returns:
             Optional[str]: A permanent unique identifying string or
-            :data:`None`. If the email address was set explicity, this will
+            :data:`None`. If the email address was set explicitly, this will
             return :data:`None`.
         """
         return self._user_id
@@ -2935,7 +2935,7 @@ class UserProperty(Property):
             This was useful for tracking which user modifies a model instance.
         auto_current_user_add (bool): Deprecated flag. When supported, if this
             flag was set to :data:`True`, the property value would be set to
-            the urrently signed-in user he first time the model instance is
+            the currently signed-in user he first time the model instance is
             stored in the datastore, unless the property has already been
             assigned a value. This was useful for tracking which user creates
             a model instance, which may not be the same user that modifies it
@@ -4640,7 +4640,7 @@ def _gql(cls, query_string, *args, **kwargs):
 
         Args:
             query_string (str): The WHERE part of a GQL query (including the
-                WHERE kwyword).
+                WHERE keyword).
             args: if present, used to call bind() on the query.
             kwargs: if present, used to call bind() on the query.
 
@@ -4964,7 +4964,7 @@ def _allocate_ids_async(
                 operation.
 
         Returns:
-            tasklets.Future: Eventural result is ``tuple(key.Key)``: Keys for
+            tasklets.Future: Eventual result is ``tuple(key.Key)``: Keys for
                 the newly allocated IDs.
         """
         if max:
@@ -5423,7 +5423,7 @@ def _populate(self, **kwargs):
         provision for key, id, or parent are made.
 
         Arguments:
-            **kwargs: Keyword arguments corresponding to poperties of this
+            **kwargs: Keyword arguments corresponding to properties of this
                 model class.
         """
         self._set_attributes(kwargs)

src/google/cloud/ndb/polymodel.py

@@ -144,7 +144,7 @@ class PolyModel(model.Model):
     Properties that are defined in a given base class within a
     hierarchy are stored in Cloud Datastore for all subclasses only.
     So, if the Feline class had a property called `whiskers`, the Cat
-    and Panther enties would also have whiskers, but not Animal,
+    and Panther entities would also have whiskers, but not Animal,
     Canine, Dog or Wolf.
 
     Polymorphic queries:

src/google/cloud/ndb/query.py

@@ -272,7 +272,7 @@ class Parameter(ParameterizedThing):
     """Represents a bound variable in a GQL query.
 
     ``Parameter(1)`` corresponds to a slot labeled ``:1`` in a GQL query.
-    ``Parameter('xyz')`` corresponds to a slot labeled ``:xyz``.
+    ``Parameter('something')`` corresponds to a slot labeled ``:something``.
 
     The value must be set (bound) separately.
 
@@ -993,7 +993,7 @@ def resolve(self, bindings, used):
 
         Returns:
             Node: The current node, if all nodes are already resolved.
-            Otherwise returns a modifed :class:`ConjunctionNode` with
+            Otherwise returns a modified :class:`ConjunctionNode` with
             each individual node resolved.
         """
         resolved_nodes = [node.resolve(bindings, used) for node in self._nodes]
@@ -1076,7 +1076,7 @@ def resolve(self, bindings, used):
 
         Returns:
             Node: The current node, if all nodes are already resolved.
-            Otherwise returns a modifed :class:`DisjunctionNode` with
+            Otherwise returns a modified :class:`DisjunctionNode` with
             each individual node resolved.
         """
         resolved_nodes = [node.resolve(bindings, used) for node in self._nodes]
@@ -1543,7 +1543,7 @@ def bind(self, *positional, **keyword):
         When a query is created using gql, any bound parameters
         are created as ParameterNode instances. This method
         receives values for both positional (:1, :2, etc.) or
-        keyword (:xyz, :abc, etc.) bound parameters, then sets the
+        keyword (:something, :other, etc.) bound parameters, then sets the
         values accordingly. This mechanism allows easy reuse of a
         parameterized query, by passing the values to bind here.
 
@@ -2086,7 +2086,7 @@ def count(
             ``len(q.fetch(limit, keys_only=True))``. We can also avoid
             marshalling NDB key objects from the returned protocol buffers, but
             this is a minor savings--most applications that use NDB will have
-            their perfomance bound by the Datastore backend, not the CPU.
+            their performance bound by the Datastore backend, not the CPU.
             Generally, any claim of performance improvement using this versus
             the equivalent call to ``fetch`` is exaggerated, at best.
 

src/google/cloud/ndb/tasklets.py

@@ -240,7 +240,7 @@ def cancel(self):
         raise NotImplementedError
 
     def cancelled(self):
-        """Get whether task for this future has been cancelled.
+        """Get whether task for this future has been canceled.
 
         Returns:
             :data:`False`: Always.

test_utils/test_utils/scripts/update_docs.sh

@@ -36,6 +36,17 @@ function build_docs {
     return $?
 }
 
+# Function to check spelling.
+function check_spelling {
+    sphinx-build \
+        -W -N \
+        -b spelling \
+        -d docs/_build/doctrees \
+        docs/ \
+        docs/_build/html/
+    return $?
+}
+
 # Only update docs if we are on CircleCI.
 if [[ "${CIRCLE_BRANCH}" == "master" ]] && [[ -z "${CIRCLE_PR_NUMBER}" ]]; then
     echo "Building new docs on a merged commit."
@@ -49,6 +60,7 @@ else
     echo "Not on master nor a release tag."
     echo "Building new docs for testing purposes, but not deploying."
     build_docs
+    check_spelling
     exit $?
 fi