Automatically check if modules are left out of the API docs

[dhermes]

See previous comment for context.

[dhermes]

/cc @tseaver We may be able to handle this with http://sphinx-doc.org/ext/coverage.html

[tseaver]

I will try to enable sphinx.ext.coverage.

[tseaver]

Per Takayuki Shimizukawa's EP 2015 presentation, the extension generates a ReST report for undocumented modules/classes/functions, but there is no CI integration for it: the command always succeeds, and does not generate a useful machine-readable file we could interrogate.

[dhermes]

I have a hacky but short way to check this.

import os
import warnings

from sphinx.ext.intersphinx import fetch_inventory

class SphinxApp(object):
    warn = warnings.warn
    srcdir = os.path.abspath('.')

I = fetch_inventory(SphinxApp, '',
                    os.path.join('docs', '_build', 'html', 'objects.inv'))
sphinx_mods = I['py:module'].keys()

py_files = []
for path, _, files in os.walk('gcloud'):
    if any([part.startswith('_')
            for part in path.split(os.path.sep)]):
        continue
    for fi in files:
        if (fi.endswith('.py') and not fi.startswith('test_')
                and not fi.startswith('_')):
            py_files.append(os.path.join(path, fi))
mods = [fi[:-3].replace(os.path.sep, '.') for fi in py_files]
print set(sphinx_mods) - set(mods)
print set(mods) - set(sphinx_mods)

---

Running this results in an empty set (everything in sphinx_mods is in mods) and the following:

{'gcloud.bigquery.query',
 'gcloud.bigtable.client',
 'gcloud.bigtable.cluster',
 'gcloud.bigtable.column_family',
 'gcloud.bigtable.row',
 'gcloud.bigtable.table',
 'gcloud.datastore.demo.demo',
 'gcloud.datastore.helpers',
 'gcloud.demo',
 'gcloud.environment_vars',
 'gcloud.iterator',
 'gcloud.storage.batch',
 'gcloud.storage.demo.demo',
 'gcloud.streaming.buffered_stream',
 'gcloud.streaming.exceptions',
 'gcloud.streaming.http_wrapper',
 'gcloud.streaming.stream_slice',
 'gcloud.streaming.transfer',
 'gcloud.streaming.util'}

We could do as we do in run_pylint.py and manually specify which files we are happy to ignore.

---

@tseaver WDYT?