From 4e3e89b77c632776dffbd04f7c4234c6d8993e8c Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Mon, 17 Sep 2018 14:40:51 -0400 Subject: [PATCH] Prep firestore docs for repo split. - Move docs from 'docs/datastore' into 'datastore/docs' and leave symlink. - Harmonize / DRY 'datastore/README.rst' and 'datastore/docs/index.rst'. - Remove docs for GAPIC-generated bits (they aren't part of the surface). - Ensure that docs still build from top-level. Toward #5912. --- docs/firestore | 1 + docs/firestore/changelog.md | 1 - docs/firestore/index.rst | 36 ------- firestore/README.rst | 97 ++++++++++++------- {docs/firestore => firestore/docs}/batch.rst | 0 firestore/docs/changelog.md | 1 + {docs/firestore => firestore/docs}/client.rst | 0 .../docs}/collection.rst | 0 .../docs}/constants.rst | 0 .../firestore => firestore/docs}/document.rst | 0 firestore/docs/gapic/v1beta1/api.rst | 6 -- firestore/docs/gapic/v1beta1/types.rst | 5 - firestore/docs/index.rst | 91 ++++------------- {docs/firestore => firestore/docs}/query.rst | 0 .../docs}/transaction.rst | 0 {docs/firestore => firestore/docs}/types.rst | 4 +- 16 files changed, 84 insertions(+), 158 deletions(-) create mode 120000 docs/firestore delete mode 120000 docs/firestore/changelog.md delete mode 100644 docs/firestore/index.rst rename {docs/firestore => firestore/docs}/batch.rst (100%) create mode 120000 firestore/docs/changelog.md rename {docs/firestore => firestore/docs}/client.rst (100%) rename {docs/firestore => firestore/docs}/collection.rst (100%) rename {docs/firestore => firestore/docs}/constants.rst (100%) rename {docs/firestore => firestore/docs}/document.rst (100%) delete mode 100644 firestore/docs/gapic/v1beta1/api.rst delete mode 100644 firestore/docs/gapic/v1beta1/types.rst rename {docs/firestore => firestore/docs}/query.rst (100%) rename {docs/firestore => firestore/docs}/transaction.rst (100%) rename {docs/firestore => firestore/docs}/types.rst (63%) diff --git a/docs/firestore b/docs/firestore new file mode 120000 index 000000000000..3c1d977bafcf --- /dev/null +++ b/docs/firestore @@ -0,0 +1 @@ +../firestore/docs/ \ No newline at end of file diff --git a/docs/firestore/changelog.md b/docs/firestore/changelog.md deleted file mode 120000 index d5bcc68e1388..000000000000 --- a/docs/firestore/changelog.md +++ /dev/null @@ -1 +0,0 @@ -../../firestore/CHANGELOG.md \ No newline at end of file diff --git a/docs/firestore/index.rst b/docs/firestore/index.rst deleted file mode 100644 index beba9c814603..000000000000 --- a/docs/firestore/index.rst +++ /dev/null @@ -1,36 +0,0 @@ -Firestore -========= - -.. toctree:: - :maxdepth: 2 - :hidden: - - constants - client - collection - document - query - batch - transaction - types - changelog - -Installation ------------- - -Install the ``google-cloud-firestore`` library using ``pip``: - -.. code-block:: console - - $ pip install google-cloud-firestore - -Usage ------ - -.. automodule:: google.cloud.firestore_v1beta1 -.. autoclass:: google.cloud.firestore_v1beta1.GeoPoint - :members: - :show-inheritance: -.. autoexception:: google.cloud.firestore_v1beta1.ReadAfterWriteError - :members: - :show-inheritance: diff --git a/firestore/README.rst b/firestore/README.rst index fbcd28ae7a9f..021e6b34db56 100644 --- a/firestore/README.rst +++ b/firestore/README.rst @@ -1,61 +1,80 @@ Python Client for Google Cloud Firestore ======================================== - Python idiomatic client for `Cloud Firestore`_ +|pypi| |versions| -.. _Cloud Firestore: https://cloud.google.com/firestore/docs/ +The `Google Cloud Firestore`_ API is a flexible, scalable +database for mobile, web, and server development from Firebase and Google +Cloud Platform. Like Firebase Realtime Database, it keeps your data in +sync across client apps through realtime listeners and offers offline support +for mobile and web so you can build responsive apps that work regardless of +network latency or Internet connectivity. Cloud Firestore also offers seamless +integration with other Firebase and Google Cloud Platform products, +including Cloud Functions. -- `Documentation`_ +- `Product Documentation`_ +- `Client Library Documentation`_ -.. _Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/firestore/client.html +.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-firestore.svg + :target: https://pypi.org/project/google-cloud-firestore/ +.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-firestore.svg +.. _Google Cloud Firestore: https://cloud.google.com/firestore/ +.. _Product Documentation: https://cloud.google.com/firestore/docs/ +.. _Client Library Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/firestore/index.html 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-firestore +1. `Select or create a Cloud Platform project.`_ +2. `Enable billing for your project.`_ +3. `Enable the Google Cloud Firestore 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 Firestore API.: https://cloud.google.com/firestore +.. _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 +~~~~~~~~~~~~ -Authentication --------------- +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. -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. +With `virtualenv`_, it's possible to install this library without needing system +install permissions, and without clashing with the installed system +dependencies. -.. _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 +.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/ -Using the API -------------- -`Cloud Firestore`_ (`Firestore API docs`_) is a flexible, scalable -database for mobile, web, and server development from Firebase and Google -Cloud Platform. Like Firebase Realtime Database, it keeps your data in -sync across client apps through realtime listeners and offers offline support -for mobile and web so you can build responsive apps that work regardless of -network latency or Internet connectivity. Cloud Firestore also offers seamless -integration with other Firebase and Google Cloud Platform products, -including Cloud Functions. +Mac/Linux +^^^^^^^^^ -.. _Firestore API docs: https://cloud.google.com/firestore/docs/ +.. code-block:: console -See the ``google-cloud-python`` API `firestore documentation`_ to learn how to -interact with the Cloud Firestore using this Client Library. + pip install virtualenv + virtualenv + source /bin/activate + /bin/pip install google-cloud-firestore -.. _firestore documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/firestore/client.html -See the `official Cloud Firestore documentation`_ for more details on -how to activate Cloud Firestore for your project. +Windows +^^^^^^^ -.. _official Cloud Firestore documentation: https://cloud.google.com/firestore/docs/ +.. code-block:: console + + pip install virtualenv + virtualenv + \Scripts\activate + \Scripts\pip.exe install google-cloud-firestore + + +Example Usage +~~~~~~~~~~~~~ .. code:: python @@ -76,3 +95,11 @@ how to activate Cloud Firestore for your project. for doc in docs: print(u'{} => {}'.format(doc.id, doc.to_dict())) + +Next Steps +~~~~~~~~~~ + +- Read the `Client Library Documentation`_ for Google Cloud Firestore API + API to see other available methods on the client. +- Read the `Product Documentation`_ to learn + more about the product and see How-to Guides. diff --git a/docs/firestore/batch.rst b/firestore/docs/batch.rst similarity index 100% rename from docs/firestore/batch.rst rename to firestore/docs/batch.rst diff --git a/firestore/docs/changelog.md b/firestore/docs/changelog.md new file mode 120000 index 000000000000..04c99a55caae --- /dev/null +++ b/firestore/docs/changelog.md @@ -0,0 +1 @@ +../CHANGELOG.md \ No newline at end of file diff --git a/docs/firestore/client.rst b/firestore/docs/client.rst similarity index 100% rename from docs/firestore/client.rst rename to firestore/docs/client.rst diff --git a/docs/firestore/collection.rst b/firestore/docs/collection.rst similarity index 100% rename from docs/firestore/collection.rst rename to firestore/docs/collection.rst diff --git a/docs/firestore/constants.rst b/firestore/docs/constants.rst similarity index 100% rename from docs/firestore/constants.rst rename to firestore/docs/constants.rst diff --git a/docs/firestore/document.rst b/firestore/docs/document.rst similarity index 100% rename from docs/firestore/document.rst rename to firestore/docs/document.rst diff --git a/firestore/docs/gapic/v1beta1/api.rst b/firestore/docs/gapic/v1beta1/api.rst deleted file mode 100644 index 56607e2b98ac..000000000000 --- a/firestore/docs/gapic/v1beta1/api.rst +++ /dev/null @@ -1,6 +0,0 @@ -Client for Google Cloud Firestore API -===================================== - -.. automodule:: google.cloud.firestore_v1beta1 - :members: - :inherited-members: \ No newline at end of file diff --git a/firestore/docs/gapic/v1beta1/types.rst b/firestore/docs/gapic/v1beta1/types.rst deleted file mode 100644 index ae3740065ccc..000000000000 --- a/firestore/docs/gapic/v1beta1/types.rst +++ /dev/null @@ -1,5 +0,0 @@ -Types for Google Cloud Firestore API Client -=========================================== - -.. automodule:: google.cloud.firestore_v1beta1.types - :members: \ No newline at end of file diff --git a/firestore/docs/index.rst b/firestore/docs/index.rst index 792fbb605f8b..9091d3157921 100644 --- a/firestore/docs/index.rst +++ b/firestore/docs/index.rst @@ -1,83 +1,28 @@ -Python Client for Google Cloud Firestore API (`Alpha`_) -======================================================= +.. include:: /../firestore/README.rst -`Google Cloud Firestore API`_: -- `Client Library Documentation`_ -- `Product Documentation`_ - -.. _Alpha: https://github.com/GoogleCloudPlatform/google-cloud-python/blob/master/README.rst -.. _Google Cloud Firestore API: https://cloud.google.com/firestore -.. _Client Library Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/firestore/usage.html -.. _Product Documentation: https://cloud.google.com/firestore - -Quick Start ------------ - -In order to use this library, you first need to go through the following steps: - -1. `Select or create a Cloud Platform project.`_ -2. `Enable billing for your project.`_ -3. `Enable the Google Cloud Firestore API.`_ -4. `Setup Authentication.`_ - -.. _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 Firestore API.: https://cloud.google.com/firestore -.. _Setup Authentication.: https://googlecloudplatform.github.io/google-cloud-python/latest/core/auth.html - -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. - -With `virtualenv`_, it's possible to install this library without needing system -install permissions, and without clashing with the installed system -dependencies. - -.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/ - - -Mac/Linux -^^^^^^^^^ - -.. code-block:: console - - pip install virtualenv - virtualenv - source /bin/activate - /bin/pip install google-cloud-firestore - - -Windows -^^^^^^^ +API Reference +------------- -.. code-block:: console +.. toctree:: + :maxdepth: 2 - pip install virtualenv - virtualenv - \Scripts\activate - \Scripts\pip.exe install google-cloud-firestore + client + collection + document + query + batch + transaction + constants + types -Next Steps -~~~~~~~~~~ -- Read the `Client Library Documentation`_ for Google Cloud Firestore API - API to see other available methods on the client. -- Read the `Google Cloud Firestore API Product documentation`_ to learn - more about the product and see How-to Guides. -- View this `repository’s main README`_ to see the full list of Cloud - APIs that we cover. +Changelog +--------- -.. _Google Cloud Firestore API Product documentation: https://cloud.google.com/firestore -.. _repository’s main README: https://github.com/GoogleCloudPlatform/google-cloud-python/blob/master/README.rst +For a list of all ``google-cloud-datastore`` releases: -Api Reference -------------- .. toctree:: - :maxdepth: 2 + :maxdepth: 2 - gapic/v1beta1/api - gapic/v1beta1/types + changelog diff --git a/docs/firestore/query.rst b/firestore/docs/query.rst similarity index 100% rename from docs/firestore/query.rst rename to firestore/docs/query.rst diff --git a/docs/firestore/transaction.rst b/firestore/docs/transaction.rst similarity index 100% rename from docs/firestore/transaction.rst rename to firestore/docs/transaction.rst diff --git a/docs/firestore/types.rst b/firestore/docs/types.rst similarity index 63% rename from docs/firestore/types.rst rename to firestore/docs/types.rst index ade96e9a990c..c2ef8ee2d136 100644 --- a/docs/firestore/types.rst +++ b/firestore/docs/types.rst @@ -1,5 +1,5 @@ -Firestore Protobuf Types -~~~~~~~~~~~~~~~~~~~~~~~~ +Types +~~~~~ .. automodule:: google.cloud.firestore_v1beta1.types :members: