Spanner docs are outdated

[vkedia]

Spanner docs still talk about checking out a session and then doing operations on that such as session.snapshot and session.batch.
We changed the API long time back where such operations can be done directly on the database object and that is the API we want to promote. Please audit all the docs to scrub out all the calls directly made on session object and replace those with calls on Database object. This should be doe before Beta since we expect an uptick in usage once we mark the client as Beta and we want to people to use the preferred API.

[vkedia]

cc @lukesneeringer @bjwatson @danoscarmike

[vkedia]

Also the snapshot doc should talk about nuances of using Snapshots with multi use and single use and the fact that users need to call begin if they need to have multiple pending operations.

[tseaver]

I presume we will drop discussion of sessions from the narrative / usage docs, but leave the API docs pages in place (since users might still come across them, e.g. in tracebacks).

[vkedia]

Yeah I agree leaving the API docs pages in place is OK. We can probably emphasise on those API docs that most users need not interact with these objects directly.

[vkedia]

cc @lukesneeringer @danoscarmike
I don;t think this has been completely resolved. For eg the transactions doc still talks about using a session and does not mention database.run_in_transaction method:
https://googlecloudplatform.github.io/google-cloud-python/stable/spanner/transaction-usage.html

Ditto for snapshots page:
https://googlecloudplatform.github.io/google-cloud-python/stable/spanner/snapshot-usage.html

Can we please reopen this bug? I would also like this to be fixed before marking the client library as GA.

[chemelnucfin]

I'm trying to write tests for spanner and I'm also having problems trying to use it from reading the documentation.