Adding Pylint plugin to check Sphinx docstrings.

[dhermes]

Also

• Updated docstrings which don't pass / are invalid.
• Integrated plugin with tox lint rule and run_pylint.
• Fixed a elif _GAECreds is not None and isinstance(credentials, _GAECreds): in gcloud.credentials._get_service_account_name.

For now, pulling directly from the mercurial source repository to get the check_docs pylint extension. The maintainer mentioned this will be released July 15-17, 2015.

See:
http://www.bitbucket.org/logilab/pylint/pull-request/143/

[review-ninja]

[dhermes]

@tseaver Sorry about reviewninja. I was toying around with it and didn't realize it had privileges to comment on GitHub. I have now disabled that.

[tseaver]

This is kind of an ugly, wide-ranging change to be merging in the middle of other development (it is going to cause conflicts for pretty much any WIP / open PR.

[dhermes]

@tseaver I'm with you on most of that (not sure I buy that it's ugly, but some of the diffs are hard to grok).

But do we ever foresee a time where we won't be in the middle of development? This likely won't cause merge issues because it touches docstrings whereas most code changes will touch code.

Did you have your dataset -> client rename in mind or something else?

As for open PRs, it is definitely going to be an issue, but again, one we can't really avoid. As you can see from these changes, we had a lot of docstrings that weren't actually documenting the methods / classes / functions correctly.

[dhermes]

@tseaver How do you see a merge going? I assume you finished your review?

[tseaver]

If you can stand the merge problems this issue creates, go ahead and merge (I would be tempted to defer this until a "janitorial" phase, myself).

[dhermes]

I checked the open PRs (12 - this one = 11) and there is nothing with any real conflict.

• Fixes #937 - Adds HTTP method and URL to exceptions. #938 will have an issue with an undocumented function arg
• Initial commit of Resource Manager API #933 and Initial commit of Cloud Search API #892: Half-baked initial commits for new APIs
• Implementing topic.subscription factory. #930: No issues (all correctly documented)
• Adding the ability to set Subscription path #919 and added optional content_type to bucket.upload_file #883: Dead PR (just discussion)
• First pass at Authentication summary in docs. #830, Adding auth doc explaining all the ways to mint credentials. #805, Storage "Interface Driven Design" Document #761: RST only
• Removing projection=full from Blob/Bucket PATCH requests. #758 and Adding _base64_crc32c function for storage integrity checks. #692: Too old to be merged anyhow