Prep pubsub docs for repo split. (#6001)

- Move docs from 'docs/pubsub' into 'pubsub/docs' and leave symlink. - Harmonize / DRY 'pubsub/README.rst' and 'pubsub/docs/index.rst'. - Ensure that docs still build from top-level. Toward #5912.
googleapis · Sep 17, 2018 · b69fe81 · b69fe81
1 parent 6fa8611
commit b69fe81
Show file tree

Hide file tree

Showing 14 changed files with 86 additions and 196 deletions.
diff --git a/docs/pubsub b/docs/pubsub
@@ -0,0 +1 @@
+../pubsub/docs/
diff --git a/docs/pubsub/changelog.md b/docs/pubsub/changelog.md
diff --git a/docs/pubsub/index.rst b/docs/pubsub/index.rst
diff --git a/pubsub/README.rst b/pubsub/README.rst
@@ -1,61 +1,88 @@
 Python Client for Google Cloud Pub / Sub
 ========================================
 
-    Python idiomatic client for `Google Cloud Pub / Sub`_
+|pypi| |versions|
 
-.. _Google Cloud Pub / Sub: https://cloud.google.com/pubsub/docs
+`Google Cloud Pub / Sub`_ is a fully-managed real-time messaging service that
+allows you to send and receive messages between independent applications. You
+can leverage Cloud Pub/Sub’s flexibility to decouple systems and components
+hosted on Google Cloud Platform or elsewhere on the Internet. By building on
+the same technology Google uses, Cloud Pub / Sub is designed to provide “at
+least once” delivery at low latency with on-demand scalability to 1 million
+messages per second (and beyond).
 
-|pypi| |versions|
+Publisher applications can send messages to a ``topic`` and other applications
+can subscribe to that topic to receive the messages. By decoupling senders and
+receivers, Google Cloud Pub/Sub allows developers to communicate between
+independently written applications.
 
--  `Documentation`_
+- `Product Documentation`_
+- `Client Library Documentation`_
 
-.. _Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/pubsub/
+.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-pubsub.svg
+   :target: https://pypi.org/project/google-cloud-pubsub/
+.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-pubsub.svg
+   :target: https://pypi.org/project/google-cloud-pubsub/
+.. _Google Cloud Pub / Sub: https://cloud.google.com/pubsub/
+.. _Product Documentation: https://cloud.google.com/pubsub/docs
+.. _Client Library Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/pubsub/
 
 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-pubsub
+1. `Select or create a Cloud Platform project.`_
+2. `Enable billing for your project.`_
+3. `Enable the Google Cloud Pub / Sub 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 Pub / Sub API.:  https://cloud.google.com/pubsub
+.. _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
--------------
 
-Google `Cloud Pub/Sub`_ (`Pub/Sub API docs`_) is designed to provide reliable,
-many-to-many, asynchronous messaging between applications. Publisher
-applications can send messages to a ``topic`` and other applications can
-subscribe to that topic to receive the messages. By decoupling senders and
-receivers, Google Cloud Pub/Sub allows developers to communicate between
-independently written applications.
+Mac/Linux
+^^^^^^^^^
+
+.. code-block:: console
+
+    pip install virtualenv
+    virtualenv <your-env>
+    source <your-env>/bin/activate
+    <your-env>/bin/pip install google-cloud-pubsub
+
 
-.. _Cloud Pub/Sub: https://cloud.google.com/pubsub/docs
-.. _Pub/Sub API docs: https://cloud.google.com/pubsub/docs/reference/rest/
+Windows
+^^^^^^^
 
-See the ``google-cloud-python`` API `Pub/Sub documentation`_ to learn how to connect
-to Cloud Pub/Sub using this Client Library.
+.. code-block:: console
+
+    pip install virtualenv
+    virtualenv <your-env>
+    <your-env>\Scripts\activate
+    <your-env>\Scripts\pip.exe install google-cloud-pubsub
 
-.. _Pub/Sub documentation: http://google-cloud-python.readthedocs.io/en/latest/pubsub/index.html
 
+Example Usage
+~~~~~~~~~~~~~
 
 Publishing
-----------
+^^^^^^^^^^
 
 To publish data to Cloud Pub/Sub you must create a topic, and then publish
 messages to it
@@ -79,7 +106,7 @@ To learn more, consult the `publishing documentation`_.
 
 
 Subscribing
------------
+^^^^^^^^^^^
 
 To subscribe to data in Cloud Pub/Sub, you create a subscription based on
 the topic, and subscribe to that.
@@ -115,9 +142,3 @@ use of a callback.
 To learn more, consult the `subscriber documentation`_.
 
 .. _subscriber documentation: http://google-cloud-python.readthedocs.io/en/latest/pubsub/subscriber/index.html
-
-
-.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-pubsub.svg
-   :target: https://pypi.org/project/google-cloud-pubsub/
-.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-pubsub.svg
-   :target: https://pypi.org/project/google-cloud-pubsub/
diff --git a/pubsub/docs/changelog.md b/pubsub/docs/changelog.md
@@ -0,0 +1 @@
+../CHANGELOG.md
diff --git a/pubsub/docs/index.rst b/pubsub/docs/index.rst
@@ -0,0 +1,22 @@
+.. include:: /../pubsub/README.rst
+
+API Documentation
+-----------------
+
+.. toctree::
+  :maxdepth: 3
+
+  publisher/index
+  subscriber/index
+  types
+
+Changelog
+---------
+
+For a list of all ``google-cloud-pubsub`` releases:
+
+.. toctree::
+  :maxdepth: 2
+
+  changelog
+
diff --git a/docs/pubsub/publisher/api/client.rst → pubsub/docs/publisher/api/client.rst b/docs/pubsub/publisher/api/client.rst → pubsub/docs/publisher/api/client.rst
diff --git a/docs/pubsub/publisher/index.rst → pubsub/docs/publisher/index.rst b/docs/pubsub/publisher/index.rst → pubsub/docs/publisher/index.rst
diff --git a/docs/pubsub/subscriber/api/client.rst → pubsub/docs/subscriber/api/client.rst b/docs/pubsub/subscriber/api/client.rst → pubsub/docs/subscriber/api/client.rst
diff --git a/docs/pubsub/subscriber/api/futures.rst → pubsub/docs/subscriber/api/futures.rst b/docs/pubsub/subscriber/api/futures.rst → pubsub/docs/subscriber/api/futures.rst
diff --git a/docs/pubsub/subscriber/api/message.rst → pubsub/docs/subscriber/api/message.rst b/docs/pubsub/subscriber/api/message.rst → pubsub/docs/subscriber/api/message.rst
diff --git a/docs/pubsub/subscriber/api/scheduler.rst → pubsub/docs/subscriber/api/scheduler.rst b/docs/pubsub/subscriber/api/scheduler.rst → pubsub/docs/subscriber/api/scheduler.rst
diff --git a/docs/pubsub/subscriber/index.rst → pubsub/docs/subscriber/index.rst b/docs/pubsub/subscriber/index.rst → pubsub/docs/subscriber/index.rst
@@ -61,7 +61,7 @@ each message received.
         callback
     )
 
-This will return a 
+This will return a
 :class:`~.pubsub_v1.subscriber.futures.StreamingPullFuture`. This future allows
 you to control the background thread that is managing the subscription.
 

diff --git a/docs/pubsub/types.rst → pubsub/docs/types.rst b/docs/pubsub/types.rst → pubsub/docs/types.rst