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

dmahugh · 2020-01-16T02:21:16Z

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!

dmahugh · 2020-01-16T02:21:47Z

CC @texasmichelle as an FYI

AUTHORING_GUIDE.md

leahecole · 2020-02-10T17:47:35Z

AUTHORING_GUIDE.md

-    upload_parser = subparsers.add_parser('upload', help=upload_blob.__doc__)
-    upload_parser.add_argument('source_file_name')
-    upload_parser.add_argument('destination_blob_name')
+Creating mocks for external resources is optional, and not recommended in


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.

AUTHORING_GUIDE.md

leahecole · 2020-02-10T17:48:57Z

AUTHORING_GUIDE.md

-    app.run(host='127.0.0.1', port=8080, debug=True)
-```
-## Writing tests
+## Using nox


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

leahecole · 2020-02-10T17:50:25Z

AUTHORING_GUIDE.md

+for a list of all environment variables used by all tests. Not every test
+needs all of these variables.
+
+## Google Cloud Storage Resources


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.

AUTHORING_GUIDE.md

kurtisvg · 2020-02-12T16:39:36Z

AUTHORING_GUIDE.md

+
+Conceptually related samples under a service or API should be grouped into
+a subfolder. For example, App Engine Standard samples are under the
+[appengine/standard](https://github.com/GoogleCloudPlatform/python-docs-samples/tree/master/appengine/standard)


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

AUTHORING_GUIDE.md

kurtisvg · 2020-02-12T16:48:37Z

AUTHORING_GUIDE.md


-Again, descriptive names prevent you from having to exhaustively describe
-every parameter.
+## Arrange, Act, Assert


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)

AUTHORING_GUIDE.md

kurtisvg · 2020-02-12T16:51:50Z

AUTHORING_GUIDE.md


-    subparsers = parser.add_subparsers(dest='command')
+## External Resources


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

AUTHORING_GUIDE.md

kurtisvg · 2020-02-12T16:54:04Z

AUTHORING_GUIDE.md

+for a list of all environment variables used by all tests. Not every test
+needs all of these variables.
+
+## Google Cloud Storage Resources


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

googlebot · 2020-02-14T19:52:12Z

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.

googlebot · 2020-02-14T20:02:07Z

CLAs look good, thanks!

ℹ️ Googlers: Go here for more info.

nnegrey · 2020-02-18T16:47:20Z

AUTHORING_GUIDE.md

-        description=__doc__,
-        formatter_class=argparse.RawDescriptionHelpFormatter)
-    parser.add_argument('bucket_name', help='Your cloud storage bucket.')
+Sample code may be integrated into Google Cloud Documentation through the use


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.

nnegrey · 2020-02-18T16:50:45Z

AUTHORING_GUIDE.md

-Here's a simple docstring for a command-line application with straightforward
-usage:
+The use of [Black](https://pypi.org/project/black/) to standardize code
+formatting and simplify diffs is recommended, but optional.


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

nnegrey · 2020-02-18T16:56:44Z

AUTHORING_GUIDE.md

-```
-
-### Functions & classes
+### Functions and Classes


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

def list_blobs(bucket_name="YOUR_BUCKET_NAME"):

kurtisvg

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

leahecole

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

AUTHORING_GUIDE.md Outdated Show resolved Hide resolved

AUTHORING_GUIDE.md Outdated Show resolved Hide resolved

AUTHORING_GUIDE.md Outdated Show resolved Hide resolved

AUTHORING_GUIDE.md Outdated Show resolved Hide resolved

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 grant, davidcavazos, daniel-sanche, averikitsch, dizcology, hongalex, anguillanneuf and bradmiro 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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

dmahugh commented Jan 16, 2020

dmahugh commented Jan 16, 2020

leahecole Feb 10, 2020

leahecole Feb 10, 2020

leahecole Feb 10, 2020

kurtisvg Feb 12, 2020

kurtisvg Feb 12, 2020

kurtisvg Feb 12, 2020

kurtisvg Feb 12, 2020

kurtisvg Feb 12, 2020

googlebot commented Feb 14, 2020

googlebot commented Feb 14, 2020

nnegrey Feb 18, 2020

nnegrey Feb 18, 2020

crwilcox Mar 4, 2020

kurtisvg Mar 4, 2020

nnegrey Feb 18, 2020

kurtisvg left a comment

leahecole left a comment


		subparsers = parser.add_subparsers(dest='command')
		## External Resources

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

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

Conversation

dmahugh commented Jan 16, 2020

dmahugh commented Jan 16, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

googlebot commented Feb 14, 2020

googlebot commented Feb 14, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kurtisvg left a comment

Choose a reason for hiding this comment

leahecole left a comment

Choose a reason for hiding this comment