From b3b3b279197abcf616313cb41f782b7a7f7acb89 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Mon, 17 Sep 2018 16:01:02 -0400 Subject: [PATCH] Prep pubsub docs for repo split. - 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. --- docs/pubsub | 1 + docs/pubsub/changelog.md | 1 - docs/pubsub/index.rst | 154 ------------------ pubsub/README.rst | 101 +++++++----- pubsub/docs/changelog.md | 1 + pubsub/docs/index.rst | 22 +++ .../docs}/publisher/api/client.rst | 0 .../docs}/publisher/index.rst | 0 .../docs}/subscriber/api/client.rst | 0 .../docs}/subscriber/api/futures.rst | 0 .../docs}/subscriber/api/message.rst | 0 .../docs}/subscriber/api/scheduler.rst | 0 .../docs}/subscriber/index.rst | 2 +- {docs/pubsub => pubsub/docs}/types.rst | 0 14 files changed, 86 insertions(+), 196 deletions(-) create mode 120000 docs/pubsub delete mode 120000 docs/pubsub/changelog.md delete mode 100644 docs/pubsub/index.rst create mode 120000 pubsub/docs/changelog.md create mode 100644 pubsub/docs/index.rst rename {docs/pubsub => pubsub/docs}/publisher/api/client.rst (100%) rename {docs/pubsub => pubsub/docs}/publisher/index.rst (100%) rename {docs/pubsub => pubsub/docs}/subscriber/api/client.rst (100%) rename {docs/pubsub => pubsub/docs}/subscriber/api/futures.rst (100%) rename {docs/pubsub => pubsub/docs}/subscriber/api/message.rst (100%) rename {docs/pubsub => pubsub/docs}/subscriber/api/scheduler.rst (100%) rename {docs/pubsub => pubsub/docs}/subscriber/index.rst (99%) rename {docs/pubsub => pubsub/docs}/types.rst (100%) diff --git a/docs/pubsub b/docs/pubsub new file mode 120000 index 000000000000..75a8b87c5ae0 --- /dev/null +++ b/docs/pubsub @@ -0,0 +1 @@ +../pubsub/docs/ \ No newline at end of file diff --git a/docs/pubsub/changelog.md b/docs/pubsub/changelog.md deleted file mode 120000 index b7adb3ad5a0c..000000000000 --- a/docs/pubsub/changelog.md +++ /dev/null @@ -1 +0,0 @@ -../../pubsub/CHANGELOG.md \ No newline at end of file diff --git a/docs/pubsub/index.rst b/docs/pubsub/index.rst deleted file mode 100644 index b43d54a76261..000000000000 --- a/docs/pubsub/index.rst +++ /dev/null @@ -1,154 +0,0 @@ -####### -Pub/Sub -####### - -`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). - -.. _Google Cloud Pub/Sub: https://cloud.google.com/pubsub/ - -************ -Installation -************ - -Install the ``google-cloud-pubsub`` library using ``pip``: - -.. code-block:: console - - $ pip install google-cloud-pubsub - -******************************** -Authentication and Configuration -******************************** - -- For an overview of authentication in ``google-cloud-python``, - see :doc:`/core/auth`. - -- In addition to any authentication configuration, you should also set the - :envvar:`GOOGLE_CLOUD_PROJECT` environment variable for the project you'd - like to interact with. If the :envvar:`GOOGLE_CLOUD_PROJECT` environment - variable is not present, the project ID from JSON file credentials is used. - - If you are using Google App Engine or Google Compute Engine - this will be detected automatically. - -- After configuring your environment, create a - :class:`~google.cloud.pubsub_v1.PublisherClient` or - :class:`~google.cloud.pubsub_v1.SubscriberClient`. - -.. code-block:: python - - >>> from google.cloud import pubsub - >>> publisher = pubsub.PublisherClient() - >>> subscriber = pubsub.SubscriberClient() - -or pass in ``credentials`` explicitly. - -.. code-block:: python - - >>> from google.cloud import pubsub - >>> client = pubsub.PublisherClient( - ... credentials=creds, - ... ) - -********** -Publishing -********** - -To publish data to Cloud Pub/Sub you must create a topic, and then publish -messages to it - -.. code-block:: python - - >>> import os - >>> from google.cloud import pubsub - >>> - >>> publisher = pubsub.PublisherClient() - >>> topic = 'projects/{project_id}/topics/{topic}'.format( - ... project_id=os.getenv('GOOGLE_CLOUD_PROJECT'), - ... topic='MY_TOPIC_NAME', # Set this to something appropriate. - ... ) - >>> publisher.create_topic(topic) # raises conflict if topic exists - >>> publisher.publish(topic, b'My first message!', spam='eggs') - -To learn more, consult the :doc:`publishing documentation `. - - -*********** -Subscribing -*********** - -To subscribe to data in Cloud Pub/Sub, you create a subscription based on -the topic, and subscribe to that. - -.. code-block:: python - - >>> import os - >>> from google.cloud import pubsub - >>> - >>> subscriber = pubsub.SubscriberClient() - >>> topic = 'projects/{project_id}/topics/{topic}'.format( - ... project_id=os.getenv('GOOGLE_CLOUD_PROJECT'), - ... topic='MY_TOPIC_NAME', # Set this to something appropriate. - ... ) - >>> subscription_name = 'projects/{project_id}/subscriptions/{sub}'.format( - ... project_id=os.getenv('GOOGLE_CLOUD_PROJECT'), - ... sub='MY_SUBSCRIPTION_NAME', # Set this to something appropriate. - ... ) - >>> subscriber.create_subscription(subscription_name, topic) - -To receive messages on the subscription, you *subscribe* to the subscription. -The client opens a stream in a background process and calls a callback for each -message received. - -.. code-block:: python - - >>> def callback(message): - ... print(message.data) - ... message.ack() - >>> future = subscriber.subscribe(subscription_name, callback) - -You can use the future to block the main thread, and raise any exceptions -that originate asynchronously. - -.. code-block:: python - - >>> future.result() - -You can also cancel the future to stop receiving messages. - - -.. code-block:: python - - >>> future.cancel() - -To learn more, consult the :doc:`subscriber documentation `. - - -********** -Learn More -********** - -.. 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/pubsub/README.rst b/pubsub/README.rst index 39699fd47919..92b6fd6924bb 100644 --- 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 + source /bin/activate + /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 + \Scripts\activate + \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 new file mode 120000 index 000000000000..04c99a55caae --- /dev/null +++ b/pubsub/docs/changelog.md @@ -0,0 +1 @@ +../CHANGELOG.md \ No newline at end of file diff --git a/pubsub/docs/index.rst b/pubsub/docs/index.rst new file mode 100644 index 000000000000..f20e6ed74414 --- /dev/null +++ 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 b/pubsub/docs/publisher/api/client.rst similarity index 100% rename from docs/pubsub/publisher/api/client.rst rename to pubsub/docs/publisher/api/client.rst diff --git a/docs/pubsub/publisher/index.rst b/pubsub/docs/publisher/index.rst similarity index 100% rename from docs/pubsub/publisher/index.rst rename to pubsub/docs/publisher/index.rst diff --git a/docs/pubsub/subscriber/api/client.rst b/pubsub/docs/subscriber/api/client.rst similarity index 100% rename from docs/pubsub/subscriber/api/client.rst rename to pubsub/docs/subscriber/api/client.rst diff --git a/docs/pubsub/subscriber/api/futures.rst b/pubsub/docs/subscriber/api/futures.rst similarity index 100% rename from docs/pubsub/subscriber/api/futures.rst rename to pubsub/docs/subscriber/api/futures.rst diff --git a/docs/pubsub/subscriber/api/message.rst b/pubsub/docs/subscriber/api/message.rst similarity index 100% rename from docs/pubsub/subscriber/api/message.rst rename to pubsub/docs/subscriber/api/message.rst diff --git a/docs/pubsub/subscriber/api/scheduler.rst b/pubsub/docs/subscriber/api/scheduler.rst similarity index 100% rename from docs/pubsub/subscriber/api/scheduler.rst rename to pubsub/docs/subscriber/api/scheduler.rst diff --git a/docs/pubsub/subscriber/index.rst b/pubsub/docs/subscriber/index.rst similarity index 99% rename from docs/pubsub/subscriber/index.rst rename to pubsub/docs/subscriber/index.rst index 005b60a0dd02..7593f17b711f 100644 --- a/docs/pubsub/subscriber/index.rst +++ b/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 b/pubsub/docs/types.rst similarity index 100% rename from docs/pubsub/types.rst rename to pubsub/docs/types.rst