Skip to content

Commit 53bf519

Browse files
dhermesdhermes
committed
Adding Pub/Sub docs and JS to dedent for the section header.
Also removing tabs from docs/_static/js/main.js
1 parent 24ba02b commit 53bf519

File tree

6 files changed

+299
-251
lines changed

6 files changed

+299
-251
lines changed

‎docs/_static/js/main.js

+8-7
Original file line numberDiff line numberDiff line change
@@ -3,20 +3,21 @@ $('.nav-current').click(function(){
33
});
44

55
$('.faq-btn').click(function(){
6-
$(this).toggleClass('open');
6+
$(this).toggleClass('open');
77
});
88

99
$('.headerlink').parent().each(function() {
10-
$(this).hover(
11-
function() { $(this).children('.headerlink').show(); },
12-
function() { $(this).children('.headerlink').hide(); }
13-
);
10+
$(this).hover(
11+
function() { $(this).children('.headerlink').show(); },
12+
function() { $(this).children('.headerlink').hide(); }
13+
);
1414
});
1515

1616
$('.side-nav').children('ul:nth-child(2)').children().each(function() {
1717
var itemName = $(this).text();
18-
if (itemName !== 'Datastore' && itemName !== 'Storage') {
19-
$(this).css('padding-left','2em');
18+
if (itemName !== 'Datastore' && itemName !== 'Storage' &&
19+
itemName !== 'Pub/Sub') {
20+
$(this).css('padding-left','2em');
2021
}
2122
});
2223

‎docs/index.rst

+3
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,9 @@
1515
storage-buckets
1616
storage-acl
1717
pubsub-api
18+
pubsub-surface
19+
pubsub-subscription
20+
pubsub-topic
1821

1922

2023
Getting started

‎docs/pubsub-api.rst

+23-244
Original file line numberDiff line numberDiff line change
@@ -1,251 +1,30 @@
1-
``gcloud.pubsub`` API
2-
=====================
1+
.. toctree::
2+
:maxdepth: 1
3+
:hidden:
34

4-
Connection / Authorization
5-
--------------------------
5+
Pub/Sub
6+
-------
67

7-
- Inferred defaults used to create connection if none configured explicitly:
8+
:mod:`gcloud.pubsub`
9+
~~~~~~~~~~~~~~~~~~~~~~~
810

9-
- credentials (derived from GAE / GCE environ if present).
11+
.. automodule:: gcloud.pubsub.__init__
12+
:members:
13+
:undoc-members:
14+
:show-inheritance:
1015

11-
- ``project_id`` (derived from GAE / GCE environ if present).
16+
Connections
17+
~~~~~~~~~~~
1218

13-
- ``scopes``
19+
.. automodule:: gcloud.pubsub.connection
20+
:members:
21+
:undoc-members:
22+
:show-inheritance:
1423

24+
Interacting with the API
25+
~~~~~~~~~~~~~~~~~~~~~~~~
1526

16-
Manage topics for a project
17-
---------------------------
18-
19-
Create a new topic for the default project:
20-
21-
.. doctest::
22-
23-
>>> from gcloud.pubsub.topic import Topic
24-
>>> topic = Topic('topic_name')
25-
>>> topic.create() # API request
26-
27-
Create a new topic for an explicit project:
28-
29-
.. doctest::
30-
31-
>>> from gcloud.pubsub.topic import Topic
32-
>>> topic = Topic('topic_name', project_id='my.project')
33-
>>> topic.create() # API request
34-
35-
Check for the existance of a topic:
36-
37-
.. doctest::
38-
39-
>>> from gcloud.pubsub.topic import Topic
40-
>>> topic = Topic('topic_name')
41-
>>> topic.exists() # API request
42-
True
43-
44-
List topics for the default project:
45-
46-
.. doctest::
47-
48-
>>> from gcloud import pubsub
49-
>>> [topic.name for topic in pubsub.list_topics()] # API request
50-
['topic_name']
51-
52-
List topics for an explicit project:
53-
54-
.. doctest::
55-
56-
>>> from gcloud import pubsub
57-
>>> topics = pubsub.list_topics(project_id='my.project') # API request
58-
>>> [topic.name for topic in topics]
59-
['topic_name']
60-
61-
Delete a topic:
62-
63-
.. doctest::
64-
65-
>>> from gcloud.pubsub.topic import Topic
66-
>>> topic = Topic('topic_name')
67-
>>> topic.delete() # API request
68-
69-
70-
Publish messages to a topic
71-
---------------------------
72-
73-
Publish a single message to a topic, without attributes:
74-
75-
.. doctest::
76-
77-
>>> from gcloud.pubsub.topic import Topic
78-
>>> topic = Topic('topic_name')
79-
>>> topic.publish('this is the message_payload') # API request
80-
<message_id>
81-
82-
Publish a single message to a topic, with attributes:
83-
84-
.. doctest::
85-
86-
>>> from gcloud.pubsub.topic import Topic
87-
>>> topic = Topic('topic_name')
88-
>>> topic.publish('this is another message_payload',
89-
... attr1='value1', attr2='value2') # API request
90-
<message_id>
91-
92-
Publish a set of messages to a topic (as a single request):
93-
94-
.. doctest::
95-
96-
>>> from gcloud.pubsub.topic import Topic
97-
>>> topic = Topic('topic_name')
98-
>>> with topic.batch() as batch:
99-
... batch.publish('this is the first message_payload')
100-
... batch.publish('this is the second message_payload',
101-
... attr1='value1', attr2='value2')
102-
>>> list(batch)
103-
[<message_id1>, <message_id2>]
104-
105-
.. note::
106-
107-
The only API request happens during the ``__exit__()`` of the topic
108-
used as a context manager.
109-
110-
111-
Manage subscriptions to topics
112-
------------------------------
113-
114-
Create a new pull subscription for a topic:
115-
116-
.. doctest::
117-
118-
>>> from gcloud.pubsub.topic import Topic
119-
>>> from gcloud.pubsub.subscription import Subscription
120-
>>> topic = Topic('topic_name')
121-
>>> subscription = Subscription('subscription_name', topic)
122-
>>> subscription.create() # API request
123-
124-
Create a new pull subscription for a topic with a non-default ACK deadline:
125-
126-
.. doctest::
127-
128-
>>> from gcloud.pubsub.topic import Topic
129-
>>> from gcloud.pubsub.subscription import Subscription
130-
>>> topic = Topic('topic_name')
131-
>>> subscription = Subscription('subscription_name', ack_deadline=90)
132-
>>> subscription.create() # API request
133-
134-
Create a new push subscription for a topic:
135-
136-
.. doctest::
137-
138-
>>> ENDPOINT = 'https://example.com/hook'
139-
>>> from gcloud.pubsub.topic import Topic
140-
>>> from gcloud.pubsub.subscription import Subscription
141-
>>> topic = Topic('topic_name')
142-
>>> subscription = Subscription('subscription_name', push_endpoint=ENDPOINT)
143-
>>> subscription.create() # API request
144-
145-
Check for the existence of a subscription:
146-
147-
.. doctest::
148-
149-
>>> from gcloud.pubsub.topic import Topic
150-
>>> from gcloud.pubsub.subscription import Subscription
151-
>>> topic = Topic('topic_name')
152-
>>> subscription = Subscription('subscription_name', topic)
153-
>>> subscription.exists() # API request
154-
True
155-
156-
Convert a pull subscription to push:
157-
158-
.. doctest::
159-
160-
>>> ENDPOINT = 'https://example.com/hook'
161-
>>> from gcloud.pubsub.topic import Topic
162-
>>> from gcloud.pubsub.subscription import Subscription
163-
>>> topic = Topic('topic_name')
164-
>>> subscription = Subscription('subscription_name', topic)
165-
>>> subscription.modify_push_configuration(push_endpoint=ENDPOINT) # API request
166-
167-
Convert a push subscription to pull:
168-
169-
.. doctest::
170-
171-
>>> ENDPOINT = 'https://example.com/hook'
172-
>>> from gcloud.pubsub.topic import Topic
173-
>>> topic = Topic('topic_name')
174-
>>> subscription = Subscription('subscription_name', topic,
175-
... push_endpoint=ENDPOINT)
176-
>>> subscription.modify_push_configuration(push_endpoint=None) # API request
177-
178-
List subscriptions for a topic:
179-
180-
.. doctest::
181-
182-
>>> from gcloud.pubsub.topic import Topic
183-
>>> topic = Topic('topic_name')
184-
>>> subscriptions = topic.list_subscriptions() # API request
185-
>>> [subscription.name for subscription in subscriptions]
186-
['subscription_name']
187-
188-
Delete a subscription:
189-
190-
.. doctest::
191-
192-
>>> from gcloud.pubsub.topic import Topic
193-
>>> from gcloud.pubsub.subscription import Subscription
194-
>>> topic = Topic('topic_name')
195-
>>> subscription = Subscription('subscription_name', topic)
196-
>>> subscription.delete() # API request
197-
198-
199-
Pull messages from a subscription
200-
---------------------------------
201-
202-
Fetch pending messages for a pull subscription
203-
204-
.. note::
205-
206-
The messages will have been ACKed already.
207-
208-
.. doctest::
209-
210-
>>> from gcloud.pubsub.topic import Topic
211-
>>> from gcloud.pubsub.subscription import Subscription
212-
>>> topic = Topic('topic_name')
213-
>>> subscription = Subscription('subscription_name', topic)
214-
>>> with topic:
215-
... topic.publish('this is the first message_payload')
216-
... topic.publish('this is the second message_payload',
217-
... attr1='value1', attr2='value2')
218-
>>> messages = subscription.pull() # API request
219-
>>> [message.id for message in messages]
220-
[<message_id1>, <message_id2>]
221-
>>> [message.data for message in messages]
222-
['this is the first message_payload', 'this is the second message_payload']
223-
>>> [message.attrs for message in messages]
224-
[{}, {'attr1': 'value1', 'attr2': 'value2'}]
225-
226-
Fetch a limited number of pending messages for a pull subscription:
227-
228-
.. doctest::
229-
230-
>>> from gcloud.pubsub.topic import Topic
231-
>>> from gcloud.pubsub.subscription import Subscription
232-
>>> topic = Topic('topic_name')
233-
>>> subscription = Subscription('subscription_name', topic)
234-
>>> with topic:
235-
... topic.publish('this is the first message_payload')
236-
... topic.publish('this is the second message_payload',
237-
... attr1='value1', attr2='value2')
238-
>>> [message.id for message in subscription.pull(max_messages=1)]
239-
[<message_id1>]
240-
241-
Fetch messages for a pull subscription without blocking (none pending):
242-
243-
.. doctest::
244-
245-
>>> from gcloud.pubsub.topic import Topic
246-
>>> from gcloud.pubsub.subscription import Subscription
247-
>>> topic = Topic('topic_name')
248-
>>> subscription = Subscription('subscription_name', topic)
249-
>>> [message.id for message in subscription.pull(return_immediately=True)]
250-
[]
251-
27+
.. automodule:: gcloud.pubsub.api
28+
:members:
29+
:undoc-members:
30+
:show-inheritance:

‎docs/pubsub-subscription.rst

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Subscriptions
2+
~~~~~~~~~~~~~
3+
4+
.. automodule:: gcloud.pubsub.subscription
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:

0 commit comments

Comments
 (0)