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

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.

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.

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.

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.

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.

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.

Basically instead of get_public_modules?

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)

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.

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?

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.

Thanks

@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.

LGTM FWIW

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

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.

@dhermes ah ok good point! Thanks!

@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.

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

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 72e5823 Compare August 15, 2016 17:37

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

dhermes reviewed Aug 17, 2016
View reviewed changes

Comment thread scripts/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 thread scripts/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 ac356df Compare 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:master Aug 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

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

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

		from verify_included_modules import get_public_modules


		docstring_test_parser = doctest.DocTestParser()

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

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

Uh oh!

Fix docs datastore examples - #2039

Fix docs datastore examples#2039daspecster merged 1 commit intogoogleapis:mastergoogleapis/google-cloud-python:masterfrom daspecster:fix-docs-datastore-examplesdaspecster/google-cloud-python:fix-docs-datastore-examplesCopy head branch name to clipboard

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

Fix docs datastore examples#2039
daspecster merged 1 commit into
googleapis:masterfrom
daspecster:fix-docs-datastore-examples

daspecster commented Aug 1, 2016 •
edited
Loading

daspecster commented Aug 1, 2016 •
edited by dhermes
Loading