Prep spanner docs for repo split. (#5938)

- Move docs from 'docs/spanner' into 'spanner/docs' and leave symlink. - Harmonize / DRY 'spanner/README.rst' and 'spanner/docs/index.rst'. - Ensure that docs still build from top-level. Toward #5912.
googleapis · Sep 12, 2018 · b97b8e8 · b97b8e8
1 parent 7a7a83d
commit b97b8e8
Show file tree

Hide file tree

Showing 31 changed files with 427 additions and 93 deletions.
diff --git a/docs/index.rst b/docs/index.rst
@@ -22,7 +22,7 @@
   oslogin/index
   resource-manager/api
   runtimeconfig/usage
-  spanner/usage
+  spanner/index
   speech/index
   error-reporting/usage
   monitoring/index

diff --git a/docs/spanner b/docs/spanner
@@ -0,0 +1 @@
+../spanner/docs/
diff --git a/docs/spanner/changelog.md b/docs/spanner/changelog.md
diff --git a/spanner/README.rst b/spanner/README.rst
@@ -1,54 +1,82 @@
 Python Client for Cloud Spanner
 ===============================
 
-    Python idiomatic client for `Cloud Spanner`_.
+|pypi| |versions|
 
-.. _Cloud Spanner: https://cloud.google.com/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.
 
-|pypi| |versions|
 
--  `Documentation`_
+- `Client Library Documentation`_
+- `Product Documentation`_
 
-.. _Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/spanner/usage.html
+
+.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-spanner.svg
+   :target: https://pypi.org/project/google-cloud-spanner/
+.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-spanner.svg
+   :target: https://pypi.org/project/google-cloud-spanner/
+.. _Cloud Spanner: https://cloud.google.com/spanner/
+.. _Client Library Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/spanner/index.html
+.. _Product Documentation:  https://cloud.google.com/spanner/docs
 
 Quick Start
 -----------
 
-.. code-block:: console
+In order to use this library, you first need to go through the following steps:
 
-    $ pip install --upgrade google-cloud-spanner
+1. `Select or create a Cloud Platform project.`_
+2. `Enable billing for your project.`_
+3. `Enable the Google Cloud Datastore API.`_
+4. `Setup Authentication.`_
 
-For more information on setting up your Python development environment,
-such as installing ``pip`` and ``virtualenv`` on your system, please refer
-to `Python Development Environment Setup Guide`_ for Google Cloud Platform.
+.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project
+.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project
+.. _Enable the Google Cloud Datastore API.:  https://cloud.google.com/datastore
+.. _Setup Authentication.: https://googlecloudplatform.github.io/google-cloud-python/latest/core/auth.html
 
-.. _Python Development Environment Setup Guide: https://cloud.google.com/python/setup
+Installation
+~~~~~~~~~~~~
 
+Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to
+create isolated Python environments. The basic problem it addresses is one of
+dependencies and versions, and indirectly permissions.
 
-Authentication
---------------
+With `virtualenv`_, it's possible to install this library without needing system
+install permissions, and without clashing with the installed system
+dependencies.
 
-With ``google-cloud-python`` we try to make authentication as painless as
-possible. Check out the `Authentication section`_ in our documentation to
-learn more. You may also find the `authentication document`_ shared by all
-the ``google-cloud-*`` libraries to be helpful.
+.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/
 
-.. _Authentication section: https://google-cloud-python.readthedocs.io/en/latest/core/auth.html
-.. _authentication document: https://github.com/GoogleCloudPlatform/google-cloud-common/tree/master/authentication
 
+Mac/Linux
+^^^^^^^^^
 
-Using the API
--------------
+.. code-block:: console
 
-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. (`About Cloud Spanner`_)
+    pip install virtualenv
+    virtualenv <your-env>
+    source <your-env>/bin/activate
+    <your-env>/bin/pip install google-cloud-datastore
+
+
+Windows
+^^^^^^^
 
-.. _About Cloud Spanner: https://cloud.google.com/spanner/
+.. code-block:: console
+
+    pip install virtualenv
+    virtualenv <your-env>
+    <your-env>\Scripts\activate
+    <your-env>\Scripts\pip.exe install google-cloud-datastore
+
+
+Example Usage
+-------------
 
 
 Executing Arbitrary SQL in a Transaction
@@ -152,15 +180,10 @@ if any of the records does not already exist.
     )
 
 
-Learn More
-----------
-
-See the ``google-cloud-python`` API `Cloud Spanner documentation`_ to learn how
-to connect to Cloud Spanner using this Client Library.
+Next Steps
+~~~~~~~~~~
 
-.. _Cloud Spanner documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/spanner/usage.html
-
-.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-spanner.svg
-   :target: https://pypi.org/project/google-cloud-spanner/
-.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-spanner.svg
-   :target: https://pypi.org/project/google-cloud-spanner/
+- See the `Client Library Documentation`_ to learn how to connect to Cloud
+  Spanner using this Client Library.
+- Read the `Product documentation`_ to learn
+  more about the product and see How-to Guides.
diff --git a/.../spanner/advanced-session-pool-topics.rst → ...ner/docs/advanced-session-pool-topics.rst b/.../spanner/advanced-session-pool-topics.rst → ...ner/docs/advanced-session-pool-topics.rst
diff --git a/docs/spanner/api-reference.rst → spanner/docs/api-reference.rst b/docs/spanner/api-reference.rst → spanner/docs/api-reference.rst
diff --git a/docs/spanner/batch-api.rst → spanner/docs/batch-api.rst b/docs/spanner/batch-api.rst → spanner/docs/batch-api.rst
diff --git a/docs/spanner/batch-usage.rst → spanner/docs/batch-usage.rst b/docs/spanner/batch-usage.rst → spanner/docs/batch-usage.rst
diff --git a/spanner/docs/changelog.md b/spanner/docs/changelog.md
@@ -0,0 +1 @@
+../CHANGELOG.md
diff --git a/docs/spanner/client-api.rst → spanner/docs/client-api.rst b/docs/spanner/client-api.rst → spanner/docs/client-api.rst
diff --git a/docs/spanner/usage.rst → spanner/docs/client-usage.rst b/docs/spanner/usage.rst → spanner/docs/client-usage.rst
@@ -1,38 +1,3 @@
-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: 1
-  :titlesonly:
-  :hidden:
-
-  instance-usage
-  database-usage
-  batch-usage
-  snapshot-usage
-  transaction-usage
-  advanced-session-pool-topics
-  api-reference
-
-Installation
-============
-
-Install the ``google-cloud-spanner`` library using ``pip``:
-
-.. code-block:: console
-
-    $ pip install google-cloud-spanner
-
 Spanner Client
 ==============
 
@@ -95,13 +60,18 @@ Configuration
 
     Be sure to use the **Project ID**, not the **Project Number**.
 
+
 Warnings about Multiprocessing
--------------------------------------------------
-- When using multiprocessing, the application may hang if a
-  :class:`Client <google.cloud.spanner_v1.client.Client>` instance is created before
-  :class:`multiprocessing.Pool` or :class:`multiprocessing.Process` invokes :func:`os.fork`.
-  The issue is under investigation, but may be only happening on Macintosh and not Linux.
-  See `GRPC/GRPC#12455 <https://github.com/grpc/grpc/issues/12455#issuecomment-348578950>`_ for more information.
+------------------------------
+
+.. warning::
+   When using multiprocessing, the application may hang if a
+   :class:`Client <google.cloud.spanner_v1.client.Client>` instance is created
+   before :class:`multiprocessing.Pool` or :class:`multiprocessing.Process`
+   invokes :func:`os.fork`.  The issue is under investigation, but may be only
+   happening on Macintosh and not Linux.  See `GRPC/GRPC#12455
+   <https://github.com/grpc/grpc/issues/12455#issuecomment-348578950>`_ for
+   more information.
 
 Next Step
 ---------
@@ -114,13 +84,3 @@ 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
-
-Changelog
-=========
-
-For a list of all ``google-cloud-spanner`` releases:
-
-.. toctree::
-  :maxdepth: 2
-
-  changelog