From c49b33ad0525d23fcad54f23591a5b685d555d3c Mon Sep 17 00:00:00 2001 From: Luke Sneeringer Date: Tue, 26 Sep 2017 07:39:06 -0700 Subject: [PATCH] Improve the Spanner landing page. (#4060) --- docs/conf.py | 1 - docs/spanner/client-usage.rst | 68 ------------------------ docs/spanner/usage.rst | 98 +++++++++++++++++++++++++++++------ 3 files changed, 83 insertions(+), 84 deletions(-) delete mode 100644 docs/spanner/client-usage.rst diff --git a/docs/conf.py b/docs/conf.py index edff3a2d5356..8d7d9b3984a9 100644 --- a/docs/conf.py +++ b/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", diff --git a/docs/spanner/client-usage.rst b/docs/spanner/client-usage.rst deleted file mode 100644 index a40c064f86da..000000000000 --- a/docs/spanner/client-usage.rst +++ /dev/null @@ -1,68 +0,0 @@ -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.spanner.client import Client - client = 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**. - - -Next Step ---------- - -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. - -Next, learn about the :doc:`instance-usage`. - -.. _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 diff --git a/docs/spanner/usage.rst b/docs/spanner/usage.rst index d84e15ec5f82..87980f520501 100644 --- a/docs/spanner/usage.rst +++ b/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