Add 'sphinx.ext.coverage' to the 'tox -e docs' build.

[tseaver]

See: #714

Note that this PR does not auto-close the issue, as I have been unable to verify that the extension can be configured to generate the error we would want for missing coverage.

[dhermes]

What does this generate? Shouldn't it be added to .gitignore? Shouldn't we inspect that output with a script?

[tseaver]

What does this generate? Shouldn't it be added to .gitignore?

It generates two ReST reports in docs/_build/coverage, which are therefore already ignored. It also generates a pickle file there.

Shouldn't we inspect that output with a script?

The ReST reports are probably not worth parsing. Maybe we could arrange to interrogate the pickle file.

[tseaver]

$ .tox/docs/bin/python
Python 2.7.9 (default, Dec 16 2014, 16:59:02) 
[GCC 4.6.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> with open('docs/_build/coverage/undoc.pickle', 'rb') as f:
...     pickled = f.read()
... 
>>> from pickle import loads
>>> xxx = loads(pickled)
>>> from pprint import pprint as pp
>>> pp(xxx)
({u'gcloud.bigquery.client': {'classes': {}, 'funcs': []},
  u'gcloud.bigquery.connection': {'classes': {}, 'funcs': []},
  u'gcloud.bigquery.dataset': {'classes': {}, 'funcs': []},
  u'gcloud.bigquery.job': {'classes': {}, 'funcs': []},
  u'gcloud.bigquery.table': {'classes': {}, 'funcs': []},
  u'gcloud.client': {'classes': {}, 'funcs': []},
  u'gcloud.connection': {'classes': {}, 'funcs': []},
  u'gcloud.credentials': {'classes': {}, 'funcs': []},
  u'gcloud.datastore.batch': {'classes': {}, 'funcs': []},
  u'gcloud.datastore.client': {'classes': {}, 'funcs': []},
  u'gcloud.datastore.connection': {'classes': {}, 'funcs': []},
  u'gcloud.datastore.entity': {'classes': {}, 'funcs': []},
  u'gcloud.datastore.key': {'classes': {}, 'funcs': []},
  u'gcloud.datastore.query': {'classes': {}, 'funcs': []},
  u'gcloud.datastore.transaction': {'classes': {}, 'funcs': []},
  u'gcloud.exceptions': {'classes': {}, 'funcs': []},
  u'gcloud.pubsub.client': {'classes': {}, 'funcs': []},
  u'gcloud.pubsub.connection': {'classes': {}, 'funcs': []},
  u'gcloud.pubsub.topic': {'classes': {}, 'funcs': []},
  u'gcloud.resource_manager.client': {'classes': {}, 'funcs': []},
  u'gcloud.resource_manager.connection': {'classes': {}, 'funcs': []},
  u'gcloud.resource_manager.project': {'classes': {}, 'funcs': []},
  u'gcloud.storage.acl': {'classes': {}, 'funcs': []},
  u'gcloud.storage.blob': {'classes': {}, 'funcs': []},
  u'gcloud.storage.bucket': {'classes': {}, 'funcs': []},
  u'gcloud.storage.client': {'classes': {}, 'funcs': []},
  u'gcloud.storage.connection': {'classes': {}, 'funcs': []}},
 {})

[dhermes]

Seems useless?

[dhermes]

@tseaver I don't think Sphinx coverage is worth using.

I ran it with a new module that didn't have a corresponding RST file and also with new code in an existing module.

It failed to say anything at all about either of these cases.

---

commit 65bc23ab9f3637e273c753b3dad7c8edf0eea23a
Author: Danny Hermes <[email protected]>
Date:   Mon Sep 28 18:33:12 2015 -0700

    Fake commit.

diff --git a/f.py b/f.py
new file mode 100755
index 0000000..61a71a8
--- /dev/null
+++ b/f.py
@@ -0,0 +1,12 @@
+#!.tox/docs/bin/python
+
+import pickle
+import pprint
+import sys
+
+pprint.pprint(sys.executable)
+
+with open('docs/_build/coverage/undoc.pickle', 'rb') as fh:
+    contents = pickle.load(fh)
+
+pprint.pprint(contents)
diff --git a/gcloud/datastore/client.py b/gcloud/datastore/client.py
index b4e2dbb..deaa24a 100644
--- a/gcloud/datastore/client.py
+++ b/gcloud/datastore/client.py
@@ -460,3 +460,7 @@ class Client(_BaseClient):
         if 'namespace' not in kwargs:
             kwargs['namespace'] = self.namespace
         return Query(self, **kwargs)
+
+
+def something_not_done():
+    return 1337
diff --git a/gcloud/datastore/foo.py b/gcloud/datastore/foo.py
new file mode 100644
index 0000000..8d872f2
--- /dev/null
+++ b/gcloud/datastore/foo.py
@@ -0,0 +1,24 @@
+# Copyright 2014 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Kool aid."""
+
+
+class NeverMore(object):
+
+    def frooty_pebbles(self):
+        return self
+
+
+def sleepaway_camp():
+    return 42

[dhermes]

@tseaver ISTM we should axe this, since the output is useless