re-write authoring guide, add links to other documentation by dmahugh · Pull Request #2728 · GoogleCloudPlatform/python-docs-samples · GitHub

Note that because many sections were added or completely re-written, the diff view is not helpful. This PR adds topics covered in the Java guide (for consistency), adds links to Google Cloud documentation where appropriate, and links to specific examples in existing samples where appropriate. Some sections have been removed to avoid duplication and simplify maintenance - for example, instead of showing the license header to use, it now links to the instructions in the LICENSE file for how to insert a license header.

Feedback welcome!

CC @texasmichelle as an FYI

I'd like to add a bit here that says the exception generally is for long running operations (like AutoML). Best practice I've seen is to begin the operation, assert that the operation exists and is running, and then cancel the operation.

This section may change a little bit if we integrate @kurtisvg 's propsed noxfile changes #2806

This section might need an update, but I'm curious to hear other opinions. I feel like each sample may require resources more than just GCS - and they tend to specify the variables you need to fill in. I'm not sure that the ./resources section is kept up to date. I could be wrong though - so let's hear what the rest of the owners think!

+1 this needs to be generalized to infrastructure resources as a whole.

Should we sort based on runtime version as well? for example, appengine/standard/python3.7?

This is actually a rule of thumb for the snippets themselves. Most snippets should use the follow pattern:

Arrange - construct the API request and build the different components needed to configure the call
Act - send the request to the server and wait for a response
Assert - verify the response is a success, and act upon it (usually printing some results to show the call was successful)

Also, any external resources that are required before the test (e.g. a Cloud SQL instance) should be pass in via an environment variable. This should be limited to infrastructure - if there is some data that need to be on that instance, the test should create it as part of the test (and clean it up when complete).

+1 this needs to be generalized to infrastructure resources as a whole.

We found a Contributor License Agreement for you (the sender of this pull request), but were unable to determine that you authored the commits in this PR. Maybe you used a different email address in the git commits than was used to sign the CLA? If someone else authored these commits, then please add them to this pull request and have them confirm that they're okay with them being contributed to Google. If there are co-authors, make sure they're formatted properly.

In order to pass this check, please resolve this problem and then comment@googlebot I fixed it... If the bot doesn't comment, it means it doesn't think anything has changed.

ℹ️ Googlers: Go here for more info.

CLAs look good, thanks!

ℹ️ Googlers: Go here for more info.

May not be true across the board, but seems like our tracking tools suggest if the samples aren't in docs that we should be deleting them?

Love to hear what other folks are suggesting.

Would it be helpful to put that they should adjust the defaults of black to use black -l 79 so that it matches PEP8?

I would prefer we try to match what is being used on google-cloud-python/ python-{product} as to not be divergent. A few flake8 rules are ignored (https://github.com/googleapis/python-storage/blob/master/.flake8) and black is used with defaults.

+1 to consistency with the client repos

Should we add default args to this section as an additional option?

def list_blobs(bucket_name="YOUR_BUCKET_NAME"):

LGTM, we'll keep tracking further improvements in the doc provided. Thanks Doug!

This is fantastic, @dmahugh !

dmahugh requested a review from a team as a code owner January 16, 2020 02:21

blunderbuss-gcf Bot assigned crwilcox Jan 16, 2020

googlebot added the cla: yes This human has signed the Contributor License Agreement. label Jan 16, 2020

texasmichelle reviewed Jan 18, 2020

View reviewed changes

Comment thread AUTHORING_GUIDE.md Outdated

Comment thread AUTHORING_GUIDE.md Outdated

Comment thread AUTHORING_GUIDE.md Outdated

Comment thread AUTHORING_GUIDE.md Outdated

kurtisvg self-requested a review January 21, 2020 21:17

texasmichelle mentioned this pull request Jan 22, 2020

vision: move published samples into master #2743

Merged

leahecole requested changes Feb 10, 2020

View reviewed changes

kurtisvg suggested changes Feb 12, 2020

View reviewed changes

dmahugh requested review from anguillanneuf, averikitsch, bradmiro, crwilcox, daniel-sanche, davidcavazos, dizcology, gguuss, grant, hongalex and nnegrey as code owners February 14, 2020 19:51

googlebot added cla: no This human has *not* signed the Contributor License Agreement. and removed cla: yes This human has signed the Contributor License Agreement. labels Feb 14, 2020

dmahugh force-pushed the style-guide-cleanup branch from 2c26111 to d94bf89 Compare February 14, 2020 20:02

googlebot added cla: yes This human has signed the Contributor License Agreement. and removed cla: no This human has *not* signed the Contributor License Agreement. labels Feb 14, 2020

dmahugh force-pushed the style-guide-cleanup branch from e647b97 to d94bf89 Compare February 14, 2020 20:07

nnegrey reviewed Feb 18, 2020

View reviewed changes

kurtisvg force-pushed the style-guide-cleanup branch 2 times, most recently from 21ee08c to 8072a27 Compare April 2, 2020 21:12

kurtisvg removed request for anguillanneuf, averikitsch, bradmiro, daniel-sanche, davidcavazos, dizcology, grant and hongalex April 2, 2020 21:12

leahecole mentioned this pull request Apr 2, 2020

Create sample format guidelines for Python-docs-samples #2565

Closed

leahecole linked an issue Apr 2, 2020 that may be closed by this pull request

Create sample format guidelines for Python-docs-samples #2565

Closed

Doug Mahugh and others added 3 commits April 2, 2020 14:35

re-write authoring guide, add links to other documentation

d273cb7

Update python versions.

21a5356

Update instructions for nox.

f93453c

kurtisvg force-pushed the style-guide-cleanup branch from 8072a27 to f93453c Compare April 2, 2020 21:36

kurtisvg approved these changes Apr 2, 2020

View reviewed changes

leahecole approved these changes Apr 3, 2020

View reviewed changes

kurtisvg merged commit b5c8ae1 into GoogleCloudPlatform:master Apr 3, 2020

kurtisvg deleted the style-guide-cleanup branch April 3, 2020 19:49

re-write authoring guide, add links to other documentation by dmahugh · Pull Request #2728 · GoogleCloudPlatform/python-docs-samples · GitHub

Uh oh!

re-write authoring guide, add links to other documentation - #2728

re-write authoring guide, add links to other documentation#2728kurtisvg merged 3 commits intoGoogleCloudPlatform:masterGoogleCloudPlatform/python-docs-samples:masterfrom dmahugh:style-guide-cleanupdmahugh/python-docs-samples:style-guide-cleanupCopy head branch name to clipboard

Conversation

dmahugh commented Jan 16, 2020

Uh oh!

dmahugh commented Jan 16, 2020

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

googlebot commented Feb 14, 2020

Uh oh!

googlebot commented Feb 14, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kurtisvg left a comment

Choose a reason for hiding this comment

Uh oh!

leahecole left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

re-write authoring guide, add links to other documentation#2728
kurtisvg merged 3 commits into
GoogleCloudPlatform:masterfrom
dmahugh:style-guide-cleanup