re-write authoring guide, add links to other documentation

[dmahugh]

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]

CC @texasmichelle as an FYI

[leahecole]

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.

[leahecole]

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

[leahecole]

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!

[kurtisvg]

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

[kurtisvg]

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

[kurtisvg]

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

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

[kurtisvg]

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

[kurtisvg]

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

[googlebot]

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]

CLAs look good, thanks!

ℹ️ Googlers: Go here for more info.

[nnegrey]

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]

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

[crwilcox]

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.

[kurtisvg]

+1 to consistency with the client repos

[nnegrey]

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 !