Improve the Spanner landing page. (#4060)

docs/conf.py

@@ -122,7 +122,6 @@
     'github_user': 'GoogleCloudPlatform',
     'github_repo': 'google-cloud-python',
     'github_banner': True,
-    'travis_button': True,
     'font_family': "'Roboto', Georgia, sans",
     'head_font_family': "'Roboto', Georgia, serif",
     'code_font_family': "'Roboto Mono', 'Consolas', monospace",

docs/spanner/usage.rst

@@ -1,11 +1,21 @@
 Spanner
-=======
+^^^^^^^
+
+`Cloud Spanner`_ is the world's first fully managed relational database service
+to offer both strong consistency and horizontal scalability for
+mission-critical online transaction processing (OLTP) applications. With Cloud
+Spanner you enjoy all the traditional benefits of a relational database; but
+unlike any other relational database service, Cloud Spanner scales horizontally
+to hundreds or thousands of servers to handle the biggest transactional
+workloads.
+
+.. _Cloud Spanner: https://cloud.google.com/spanner/
 
 .. toctree::
-  :maxdepth: 2
+  :maxdepth: 1
+  :titlesonly:
   :hidden:
 
-  client-usage
   instance-usage
   database-usage
   batch-usage
@@ -14,19 +24,77 @@ Spanner
   advanced-session-pool-topics
   api-reference
 
-API requests are sent to the `Cloud Spanner`_ API via RPC over
-HTTP/2.  In order to support this, we'll rely on `gRPC`_.
+Spanner Client
+==============
+
+.. _spanner-client:
+
+
+Instantiating a Client
+----------------------
+
+To use the API, the :class:`~google.cloud.spanner.client.Client`
+class defines a high-level interface which handles authorization
+and creating other objects:
+
+.. code:: python
+
+    from google.cloud import spanner
+    client = spanner.Client()
+
+Long-lived Defaults
+-------------------
+
+When creating a :class:`~google.cloud.spanner.client.Client`, the
+``user_agent`` and ``timeout_seconds`` arguments have sensible
+defaults
+(:data:`~google.cloud.spanner.client.DEFAULT_USER_AGENT` and
+:data:`~google.cloud.spanner.client.DEFAULT_TIMEOUT_SECONDS`).
+However, you may over-ride them and these will be used throughout all API
+requests made with the ``client`` you create.
+
+Configuration
+-------------
+
+- For an overview of authentication in ``google.cloud-python``,
+  see :doc:`/core/auth`.
+
+- In addition to any authentication configuration, you can also set the
+  :envvar:`GCLOUD_PROJECT` environment variable for the Google Cloud Console
+  project you'd like to interact with. If your code is running in Google App
+  Engine or Google Compute Engine the project will be detected automatically.
+  (Setting this environment variable is not required, you may instead pass the
+  ``project`` explicitly when constructing a
+  :class:`~google.cloud.storage.client.Client`).
+
+- After configuring your environment, create a
+  :class:`~google.cloud.storage.client.Client`
+
+  .. code::
+
+     >>> from google.cloud import spanner
+     >>> client = spanner.Client()
+
+  or pass in ``credentials`` and ``project`` explicitly
+
+  .. code::
+
+     >>> from google.cloud import spanner
+     >>> client = spanner.Client(project='my-project', credentials=creds)
+
+.. tip::
+
+    Be sure to use the **Project ID**, not the **Project Number**.
+
 
-Get started by learning about the :class:`~google.cloud.spanner.client.Client`
-on the :doc:`client-usage` page.
+Next Step
+---------
 
-In the hierarchy of API concepts
+After a :class:`~google.cloud.spanner.client.Client`, the next
+highest-level object is an :class:`~google.cloud.spanner.instance.Instance`.
+You'll need one before you can interact with databases.
 
-* a :class:`~google.cloud.spanner.client.Client` owns an
-  :class:`~google.cloud.spanner.instance.Instance`
-* an :class:`~google.cloud.spanner.instance.Instance` owns a
-  :class:`~google.cloud.spanner.database.Database`
+Next, learn about the :doc:`instance-usage`.
 
-.. _Cloud Spanner: https://cloud.google.com/spanner/docs/
-.. _gRPC: http://www.grpc.io/
-.. _grpcio: https://pypi.org/project/grpcio/
+.. _Instance Admin: https://cloud.google.com/spanner/reference/rpc/google.spanner.admin.instance.v1
+.. _Database Admin: https://cloud.google.com/spanner/reference/rpc/google.spanner.admin.database.v1