Sphinx and PEP8 docstring fix

[dhermes]

Fixes too long (PEP8) single-line docstring descriptions. Fixes some Sphinx errors and warnings as well as bad links.

[dhermes]

The type gcloud.datastore.datastore_v1_pb2.Query described in datastore.query.Query.to_protobuf doesn't seem to exist? At the very least, Sphinx fails to link it.

@tseaver Do you know how this works?

[dhermes]

This is part of the ongoing work towards #179

[dhermes]

I think adding the -n nit-picky flag and -W "Turn warnings into errors" flag would be a way to satisfy #178 and likely would be worth doing for continued docs quality.

[tseaver]

The type gcloud.datastore.datastore_v1_pb2.Query described in
datastore.query.Query.to_protobuf doesn't seem to exist? At the very
least, Sphinx fails to link it.

Hmm, it imports fine as long as the 'gcloud-python' distribution is on
PYTHONPATH:

$ ../../bin/python Python 2.7.6 (default, Nov 15 2013, 11:35:43) [GCC 4.6.3] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> from gcloud.datastore.datastore_v1_pb2 import Query >>> Query <class 'gcloud.datastore.datastore_v1_pb2.Query'> 

How are you provoking the error in Sphinx? This works for me:

$ rm -r docs/_build $ tox -e docs GLOB sdist-make: /home/tseaver/projects/agendaless/Google/src/gcloud-python/setup.py docs inst-nodeps: /home/tseaver/projects/agendaless/Google/src/gcloud-python/.tox/dist/gcloud-0.02.2.zip docs runtests: PYTHONHASHSEED='1286245116' docs runtests: commands[0] | sphinx-build -b html -d docs/_build/doctrees docs docs/_build/html Making output directory... Running Sphinx v1.2.3 loading pickled environment... not yet created building [html]: targets for 9 source files that are out of date updating environment: 9 added, 0 changed, 0 removed reading sources... [100%] storage-quickstart /home/tseaver/projects/agendaless/Google/src/gcloud-python/docs/index.rst:17: WARNING: Duplicate explicit target name: "official documentation". /home/tseaver/projects/agendaless/Google/src/gcloud-python/docs/index.rst:17: WARNING: Duplicate explicit target name: "official documentation". /home/tseaver/projects/agendaless/Google/src/gcloud-python/docs/index.rst:17: WARNING: Duplicate explicit target name: "official documentation". /home/tseaver/projects/agendaless/Google/src/gcloud-python/docs/index.rst:17: WARNING: Duplicate explicit target name: "official documentation". looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] storage-quickstart writing additional files... (17 module code pages) _modules/index genindex py-modindex search copying images... [100%] _static/bigquery-logo.png copying static files... done copying extra files... done dumping search index... done dumping object inventory... done build succeeded, 4 warnings. ___________________________________ summary ____________________________________ docs: commands succeeded congratulations :) 

[dhermes]

@tseaver I don't know how I missed the class definition on my first scan of the file.

I realize now that the type exists, but doesn't show up as a link because the module isn't included in the relevant module list for the datastore package.

I didn't notice this from an error thrown by Sphinx, but rather by a doc scan of datastore-api.html after some changes I made in this PR.