Interleave doctest examples w/ API ref docs.

docs/index.rst

@@ -33,7 +33,6 @@
   :hidden:
   :caption: Pub/Sub
 
-  pubsub-usage
   Client <pubsub-client>
   pubsub-topic
   pubsub-subscription

docs/pubsub-client.rst

@@ -2,10 +2,47 @@ Pub/Sub Client
 ==============
 
 .. automodule:: gcloud.pubsub.client
-  :members:
-  :undoc-members:
   :show-inheritance:
 
+  .. autoclass:: Client
+
+    For example:
+
+    .. doctest::
+
+        >>> from gcloud import pubsub
+        >>> client = pubsub.Client()
+
+    .. automethod:: topic
+
+        For example:
+
+        .. doctest::
+
+        >>> topic = client.topic('topic-name', timestamp_messages=True)
+
+    .. automethod:: list_topics
+
+        For example, to get a list of all the topics in the project:
+
+        .. doctest::
+
+        >>> topics, token = client.list_topics()
+        >>> while token is not None:
+        ...    next_batch, token = client.list_topics(token)
+        ...    topics.extend(next_batch)
+
+    .. automethod:: list_subscriptions
+
+        For example, to get a list of all the subscriptions in the project:
+
+        .. doctest::
+
+        >>> subscriptions, token = client.list_subscriptions()
+        >>> while token is not None:
+        ...    next_batch, token = client.list_subscriptions(token)
+        ...    subscriptions.extend(next_batch)
+
 Connection
 ~~~~~~~~~~
 

docs/pubsub-subscription.rst

@@ -2,6 +2,78 @@ Subscriptions
 ~~~~~~~~~~~~~
 
 .. automodule:: gcloud.pubsub.subscription
-  :members:
-  :undoc-members:
   :show-inheritance:
+
+   .. autoclass:: Subscription
+
+     .. doctest::
+
+        >>> from gcloud.pubsub import Subscription
+        >>> subscription = Subscription('subscription-name', topic)
+
+     Normally, application code would construct a ``Topic`` instance
+     via the :meth:`gcloud.pubsub.client.Client.topic` factory rather
+     than instantiating the class directly.  For example:
+
+     .. doctest::
+
+        >>> topic = client.topic('topic-name')
+
+     .. autoattribute:: path
+
+     The following methods cause the topic to make calls to the back-end API.
+
+     .. automethod:: create
+
+        .. doctest::
+
+           >>> subscription.create()
+
+     .. automethod:: exists
+
+        .. doctest::
+
+           >>> subscription.exists()
+           True
+
+     .. automethod:: reload
+
+        .. doctest::
+
+           >>> subscription.reload()
+
+     .. automethod:: delete
+
+        .. doctest::
+
+           >>> subscription.delete()
+
+     .. automethod:: modify_push_configuration
+
+        .. doctest::
+
+           >>> subscription.modify_push_configuration('http://example.com/callback')
+
+     .. automethod:: pull
+
+        .. doctest::
+
+           >>> received = subscription.pull(max_messages=1)
+           >>> messages = [recv[1] for recv in received]
+
+     .. automethod:: modify_ack_deadline
+
+        For instance, given the previous call to ``pull``, we can delay
+        the deadline for acknowlegement:
+
+        .. doctest::
+
+           >>> ack_ids = [recv[0] for recv in received]
+           >>> for ack_id in ack_ids:
+           ...     subscription.modify_ack_deadline(ack_id, 3600)
+
+     .. automethod:: acknowledge
+
+        .. doctest::
+
+           >>> subscription.acknowledge(ack_ids)

docs/pubsub-topic.rst

@@ -2,6 +2,113 @@ Topics
 ~~~~~~
 
 .. automodule:: gcloud.pubsub.topic
-  :members:
-  :undoc-members:
   :show-inheritance:
+
+  .. autoclass:: Topic
+
+     For example:
+
+     .. doctest::
+
+        >>> from gcloud.pubsub import Topic
+        >>> topic = Topic('topic-name', client)
+
+     Normally, application code would construct a ``Topic`` instance
+     via the :meth:`gcloud.pubsub.client.Client.topic` factory rather
+     than instantiating the class directly.  For example:
+
+     .. doctest::
+
+        >>> topic = client.topic('topic-name')
+
+     .. autoattribute:: project
+
+     .. autoattribute:: path
+
+     .. autoattribute:: full_name
+
+     .. automethod:: subscription
+
+        .. doctest::
+
+           >>> subscription = topic.subscription('subscription-name')
+
+     The following methods cause the topic to make calls to the back-end API.
+
+     .. automethod:: create
+
+        .. doctest::
+
+           >>> topic.create()
+
+     .. automethod:: exists
+
+        .. doctest::
+
+           >>> topic.exists()
+           True
+
+     .. automethod:: delete
+
+        .. doctest::
+
+           >>> topic.delete()
+
+     .. automethod:: publish
+
+        For example:
+
+        .. doctest::
+
+           >>> topic.publish(b'MESSAGE_BYTES', some_key='value')
+
+     Batching allows the application to publish a set of messages to a
+     topic via a single API request.
+
+     .. automethod:: batch
+
+  .. autoclass:: Batch
+
+     .. doctest::
+
+        >>> from gcloud.pubsub.topic import Batch
+        >>> batch = Batch(topic, client)
+
+     Normally, application code would construct a ``Batch`` instance
+     via the :meth:`gcloud.pubsub.topic.Topic.batch` factory rather
+     than instantiating the class directly.  For example:
+
+     .. doctest::
+
+        >>> batch = topic.batch()
+
+     .. automethod:: publish
+
+        .. doctest::
+
+           >>> batch = topic.batch()
+           >>> batch.publish('this is the first message_payload')
+           >>> batch.publish('this is the second message_payload',
+           ...                   attr1='value1', attr2='value2')
+           >>> list(batch)
+           [<message_id1>, <message_id2>]
+
+     .. automethod:: commit
+
+        For example, given the previous calls to ``pubilsh``:
+
+        .. doctest::
+
+           >>> batch.commit()
+
+        When the ``Batch`` is used as a context manager, its ``commit``
+        method is called automatically when the context manager exits
+        without an exception. For example, ``commit`` is called as the
+        ``with`` block exits:
+
+        .. doctest::
+
+           >>> with topic.batch() as batch:
+           ...     batch.publish('this is the first message_payload')
+           ...     batch.publish('this is the second message_payload',
+           ...                   attr1='value1', attr2='value2')