Fix #162: Document semantics of upload to existing key.

[tseaver]

Point to the 'object versioning' and 'lifetime' specs for details about
how to override the default (overwrite unconditionally).

Fixes #162.

[coveralls]

Coverage remained the same when pulling 6126d31 on tseaver:162-document-key-upload-overwrite-semantics into 632e126 on GoogleCloudPlatform:master.

[tseaver]

Rebased to pick up link "Fixes #162" in commit message.

[coveralls]

Coverage remained the same when pulling 0eefb21 on tseaver:162-document-key-upload-overwrite-semantics into 632e126 on GoogleCloudPlatform:master.

[dhermes]

LGTM but IIUC we want to use two underscores (__) for anonymous (I think that's the right term) hyperlinks in the docstring.

[tseaver]

The links render correctly in Sphinx after tox -e docs

[dhermes]

Yeah it's not a rendering thing, I was referring to something like the change in 47ce050, which stopped the following errors (since we use `-W);

.../gcloud-python/docs/index.rst:17: WARNING: Duplicate explicit target name: "official documentation".

I dug back up the post which I read to give some context:
http://stackoverflow.com/a/14067756

It won't matter unless our links have name collision, but a single underscore implies we are using that name throughout the document to refer to the URL.

It certainly doesn't matter until it does, but is good to know about Sphinx.

Feel free to merge and we can refer back here if we ever go have name collision. In general, double underscores is what we want. AFAICT we don't have any named hyperlinks in this project.

[tseaver]

That problem arose from using the same link text to refer to different URLs within the same file. We dont's have that issue here, I think.

[dhermes]

Yes, and that's because that link text (when not anonymous, i.e. single underscore) is also the link name in a global namespace. So when multiple links have the same name, there is a collision, unless they are anonymous (double underscore).

Again, feel free to merge, just keep this in mind going forward.