Fix docs datastore examples by daspecster · Pull Request #2039 · googleapis/google-cloud-python

daspecster · 2016-08-01T17:31:44Z

Fixes#2037.

This is a partial fix for the datastore docstring issue.

The original issue was actually, in part, due to the examples being in the datastore.Connection class. Sphinx put them all on one page for some reason.

Sign in to view

 if element.docstring:
 if not isinstance(element, pdoc.Class) and element.cls:
-cls = element.cls.cls
+clas = element.cls.cls


dhermes · 2016-08-01T18:33:14Z

The original issue was actually, in part, due to the examples being in the datastore.Connection class. Sphinx put them all on one page for some reason.

We have until now curated all the docs/*.rst files to make the documentation usable, so just machine generating from every module with no regard for the original hand curated docs is a bad idea.

daspecster · 2016-08-01T18:39:43Z

I agree with you there.
TBH, after going down that road a few times I wasn't able to find a good way to get all the information from the RST. AutoDoc is pretty extensive and from what I can tell it would be a pretty big undertaking to recreate that. If there is a reasonable way to do it that I missed, I'm all for it.

That's probably a bigger topic than this PR though.

dhermes · 2016-08-01T18:42:01Z

Slowly bringing the two approaches in sync would've been the right move. There is a way (one that is employed by oauth2client) to just have the files themselves be the source of truth.

daspecster · 2016-08-01T18:49:45Z

I'm not really following I guess.

sphinx-apidoc --separate --force -o docs/source oauth2client

Creates RST files with the autodoc directives in them. I guess you could grab the module references from that? But that's not a huge win in this case I don't think? I could be wrong or missing something though.

dhermes · 2016-08-01T18:58:43Z

The point is that in that regime we don't care what is in the RST files. Using sphinx-apidoc makes the Python modules the single source of truth.

daspecster · 2016-08-01T19:27:59Z

Basically instead of get_public_modules?

dhermes · 2016-08-01T21:24:13Z

I'm not referring to your handrolled solution, so get_public_modules is kind of a side-concern. I'm just saying if we went that route then it would easier map onto the concept that you've come up with (which I think was to map onto whatever has been done in gcloud-common)

daspecster · 2016-08-02T20:59:53Z

The gcloud-common site structure is different from our sphinx structure. I asked for multiple class support but didn't gain any traction. That would help match things up to what we have in Sphinx.

In anycase, I moved the example code to client.py since that's in the top level nav for the site docs. We should probably think of a strategy for handling this stuff though.

dhermes · 2016-08-02T21:50:39Z

That sounds fine, we should have an issue for this discussion. Your docstring changes seem fine, how should I vet the docgen stuff in scripts/generate_json_docs.py?

daspecster · 2016-08-02T22:06:58Z

Sure, although generate_json_docs.py is not great code and should be refactored and cleaned up.

I made #2043 to talk about what I think you were saying before.

dhermes · 2016-08-02T22:07:21Z

Thanks

daspecster · 2016-08-15T19:36:56Z

@dhermes, I didn't delete the docs from connection.py. I thought it would be good to leave it for now. Otherwise I think I got the other issues you mentioned.

Sign in to view

 # Hack for old-style classes
- if str(cls)[0] != '<':
-cls = '<class \'' + str(cls) + '\'>'
+ if str(klass)[0] != '<':


Sign in to view

 from verify_included_modules import get_public_modules


+docstring_test_parser = doctest.DocTestParser()


tseaver · 2016-08-17T19:29:54Z

LGTM FWIW

Sign in to view

+ example_str += '%s' % (example.source,)
+ example_str += '%s' % (example.want,)
+
+ return example_str.replace('<', '&lt;').replace('>', '&gt;')


Pull examples with doctest and exit less early for Method parsing. Move example docstring from connection.py->client.py Change clas to klass.

dhermes · 2016-08-17T20:27:43Z

LGTM. @daspecster on future PRs can you hold off on squashing until the PR is ready to merge? It makes it a lot harder to verify which fixes have been made during code review.

daspecster · 2016-08-17T20:29:33Z

@dhermes ah ok good point! Thanks!

daspecster · 2016-08-17T20:36:13Z

@tseaver I missed your use the six wrappers comment until after merge. But I changed that line to cgi.escape() anyway. Were you saying there is a six wrapper for cgi.escape? I didn't see anything like that in six.

tseaver · 2016-08-17T20:41:06Z

@daspecster Nope, I was mistaken: six does not have the wrapper.

dhermes · 2016-08-17T20:43:23Z

Yup. six does have urllib though (if we did go the urlencode route)

Co-authored-by: Anthonios Partheniou <partheniou@google.com>

Adds a function `determine_requested_streams()` to compare `preserve_order` and the new argument `max_stream_count` to determine how many streams to request. ``` preserve_order (bool): Whether to preserve the order of streams. If True, this limits the number of streams to one (more than one cannot guarantee order). max_stream_count (Union[int, None]]): The maximum number of streams allowed. Must be a non-negative number or None, where None indicates the value is unset. If `max_stream_count` is set, it overrides `preserve_order`. ``` Fixes#2030 🦕

daspecster added the docs label Aug 1, 2016

daspecster assigned tseaver and dhermes Aug 1, 2016

googlebot added the cla: yes This human has signed the Contributor License Agreement. label Aug 1, 2016

dhermes reviewed Aug 1, 2016
View reviewed changes

daspecster mentioned this pull request Aug 2, 2016
Documentation site generation strategy #2043
Closed

daspecster force-pushed the fix-docs-datastore-examples branch from 9101b26 to 72e5823Compare August 15, 2016 17:37

daspecster force-pushed the fix-docs-datastore-examples branch 2 times, most recently from 3dc290f to 75baf31Compare August 17, 2016 17:02

dhermes reviewed Aug 17, 2016
View reviewed changes

Comment threadscripts/generate_json_docs.py Outdated
# Hack for old-style classes
if str(cls)[0] != '<':
cls = '<class \'' + str(cls) + '\'>'
if str(klass)[0] != '<':
This comment was marked as spam.
Sign in to view

dhermes reviewed Aug 17, 2016
View reviewed changes

Comment threadscripts/generate_json_docs.py Outdated
from verify_included_modules import get_public_modules

docstring_test_parser = doctest.DocTestParser()
This comment was marked as spam.
Sign in to view

dhermes reviewed Aug 17, 2016
View reviewed changes

Move examples to query docstring.
ac356df
Pull examples with doctest and exit less early for Method parsing. Move example docstring from connection.py->client.py Change clas to klass.

daspecster force-pushed the fix-docs-datastore-examples branch from 588f301 to ac356dfCompare August 17, 2016 20:03

daspecster mentioned this pull request Aug 17, 2016
The link to the API documentation has changed. #2069
Closed

daspecster merged commit 536377a into googleapis:masterAug 17, 2016

dhermes mentioned this pull request Sep 19, 2016
Cut 0.19.0 release. #2270
Merged

daspecster deleted the fix-docs-datastore-examples branch January 24, 2017 15:18

theacodes unassigned dhermes Sep 28, 2018

parthea added a commit that referenced this pull request Nov 24, 2025
chore(deps): update dependency requests to v2.32.2 [security] (#2039)
148d272
Co-authored-by: Anthonios Partheniou <partheniou@google.com>

parthea pushed a commit that referenced this pull request Apr 1, 2026
chore: fix ops.ToTimedeltaOp and ops.IsInOp sqlglot compiler (#2039)
b0e037e

		from verify_included_modules import get_public_modules


		docstring_test_parser = doctest.DocTestParser()

Uh oh!

Conversation

daspecster commented Aug 1, 2016

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

dhermes commented Aug 1, 2016

Uh oh!

daspecster commented Aug 1, 2016

Uh oh!

dhermes commented Aug 1, 2016

Uh oh!

daspecster commented Aug 1, 2016• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dhermes commented Aug 1, 2016

Uh oh!

daspecster commented Aug 1, 2016• edited by dhermes Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dhermes commented Aug 1, 2016

Uh oh!

daspecster commented Aug 2, 2016

Uh oh!

dhermes commented Aug 2, 2016

Uh oh!

daspecster commented Aug 2, 2016

Uh oh!

dhermes commented Aug 2, 2016

Uh oh!

daspecster commented Aug 15, 2016

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

tseaver commented Aug 17, 2016

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

This comment was marked as spam.

Uh oh!

dhermes commented Aug 17, 2016

Uh oh!

daspecster commented Aug 17, 2016

Uh oh!

daspecster commented Aug 17, 2016

Uh oh!

tseaver commented Aug 17, 2016

Uh oh!

dhermes commented Aug 17, 2016

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

daspecster commented Aug 1, 2016•
edited
Loading

daspecster commented Aug 1, 2016•
edited by dhermes
Loading