Skip to content

Commit 073b703

Browse files
stevepiercystevepiercy
committed
- Update usage to include plone-client in the examples.
- Add narrative text to explain each example. - Change headings to be more descriptive of their content. - Add missing responses to inline examples. - Fix broken test after editing `usage.rst`
1 parent 943b2dd commit 073b703

2 files changed

Lines changed: 168 additions & 47 deletions

File tree

‎docs/usage.rst‎

Lines changed: 167 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,33 @@
1-
Examples of use
2-
===============
1+
==============
2+
Usage examples
3+
==============
4+
5+
This chapter displays reStructuredText markup examples and their renderings.
6+
7+
.. important::
8+
9+
The request and the response must be separated by at least two blank lines, and the first line in the response must start with the string ``HTTP`` followed immediately by either a forward slash ``/`` or space character.
310

411

512
Examples with inline sources
613
----------------------------
714

8-
Example 1
9-
^^^^^^^^^
15+
The following examples use reStructuredText markup with the request and response sources inline with the page.
16+
1017

11-
Code
12-
````
18+
HTTP with slash and version
19+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
20+
21+
The following example contains an HTTP ``GET`` request.
22+
It shows the response starting with ``HTTP`` followed by a forward slash, the HTTP version, and the HTTP response code.
23+
24+
25+
Markup
26+
``````
1327

1428
.. code-block:: rst
1529
16-
.. http:example:: curl wget httpie python-requests
30+
.. http:example:: curl wget httpie python-requests plone-client
1731
1832
GET /Plone/front-page HTTP/1.1
1933
Host: localhost:8080
@@ -62,15 +76,10 @@ Code
6276
"title": "Welcome to Plone"
6377
}
6478
65-
.. note::
66-
67-
Request and response must be separated with two or more blank lines and
68-
the first response line must start with string "HTTP/" or "HTTP ".
69-
7079
Result
7180
``````
7281

73-
.. http:example:: curl wget httpie python-requests
82+
.. http:example:: curl wget httpie python-requests plone-client
7483
7584
GET /Plone/front-page HTTP/1.1
7685
Host: localhost:8080
@@ -119,9 +128,70 @@ Result
119128
"title": "Welcome to Plone"
120129
}
121130

122-
or with inline response starting with just "HTTP " without the HTTP version:
131+
HTTP with space, no version
132+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
133+
134+
The following example is exactly the same as the previous one, except the response starts with ``HTTP`` without a slash and HTTP version, followed by a space and the HTTP response code.
135+
136+
Markup
137+
``````
138+
139+
.. code-block:: rst
140+
141+
.. http:example:: curl wget httpie python-requests plone-client
142+
143+
GET /Plone/front-page HTTP/1.1
144+
Host: localhost:8080
145+
Accept: application/json
146+
Authorization: Basic YWRtaW46YWRtaW4=
147+
148+
149+
HTTP 200 OK
150+
Content-Type: application/json
151+
152+
{
153+
"@id": "http://localhost:8080/Plone/front-page",
154+
"@type": "Document",
155+
"UID": "1f699ffa110e45afb1ba502f75f7ec33",
156+
"allow_discussion": null,
157+
"changeNote": "",
158+
"contributors": [],
159+
"created": "2016-01-21T01:14:48+00:00",
160+
"creators": [
161+
"test_user_1_",
162+
"admin"
163+
],
164+
"description": "Congratulations! You have successfully installed Plone.",
165+
"effective": null,
166+
"exclude_from_nav": false,
167+
"expires": null,
168+
"id": "front-page",
169+
"language": "",
170+
"modified": "2016-01-21T01:24:11+00:00",
171+
"parent": {
172+
"@id": "http://localhost:8080/Plone",
173+
"@type": "Plone Site",
174+
"description": "",
175+
"title": "Plone site"
176+
},
177+
"relatedItems": [],
178+
"review_state": "private",
179+
"rights": "",
180+
"subjects": [],
181+
"table_of_contents": null,
182+
"text": {
183+
"content-type": "text/plain",
184+
"data": "If you're seeing this instead of the web site you were expecting, the owner of this web site has just installed Plone. Do not contact the Plone Team or the Plone mailing lists about this.",
185+
"encoding": "utf-8"
186+
},
187+
"title": "Welcome to Plone"
188+
}
189+
123190
124-
.. http:example:: curl wget httpie python-requests
191+
Result
192+
``````
193+
194+
.. http:example:: curl wget httpie python-requests plone-client
125195
126196
GET /Plone/front-page HTTP/1.1
127197
Host: localhost:8080
@@ -171,22 +241,29 @@ or with inline response starting with just "HTTP " without the HTTP version:
171241
}
172242

173243

174-
Example 2
175-
^^^^^^^^^
244+
HTTP ``POST``
245+
^^^^^^^^^^^^^
176246

177-
Code
178-
````
247+
The following example contains an HTTP ``POST`` request and its response.
248+
249+
250+
Markup
251+
``````
179252

180253
.. code-block:: rst
181254
182-
.. http:example:: curl wget httpie python-requests
255+
.. http:example:: curl wget httpie python-requests plone-client
183256
184257
POST /Plone/folder HTTP/1.1
185258
Host: localhost:8080
186259
Accept: application/json
187260
Content-Type: application/json
188261
Authorization: Basic YWRtaW46YWRtaW4=
189262
263+
264+
HTTP 200 OK
265+
Content-Type: application/json
266+
190267
{
191268
"@type": "Document",
192269
"title": "My Document"
@@ -195,35 +272,47 @@ Code
195272
Result
196273
``````
197274

198-
.. http:example:: curl wget httpie python-requests
275+
.. http:example:: curl wget httpie python-requests plone-client
199276
200277
POST /Plone/folder HTTP/1.1
201278
Host: localhost:8080
202279
Accept: application/json
203280
Content-Type: application/json
204281
Authorization: Basic YWRtaW46YWRtaW4=
205282

283+
284+
HTTP 200 OK
285+
Content-Type: application/json
286+
206287
{
207288
"@type": "Document",
208289
"title": "My Document"
209290
}
210291

211-
Example 3
212-
^^^^^^^^^
213292

214-
Code
215-
````
293+
HTTP ``PATCH``
294+
^^^^^^^^^^^^^^
295+
296+
The following example contains an HTTP ``PATCH`` request and its response.
297+
298+
299+
Markup
300+
``````
216301

217302
.. code-block:: rst
218303
219-
.. http:example:: curl wget httpie python-requests
304+
.. http:example:: curl wget httpie python-requests plone-client
220305
221306
PATCH /Plone/folder/my-document HTTP/1.1
222307
Host: localhost:8080
223308
Content-Type: application/json
224309
Accept: application/json
225310
Authorization: Basic YWRtaW46YWRtaW4=
226311
312+
313+
HTTP 200 OK
314+
Content-Type: application/json
315+
227316
{
228317
"title": "My New Document Title"
229318
}
@@ -239,16 +328,23 @@ Result
239328
Accept: application/json
240329
Authorization: Basic YWRtaW46YWRtaW4=
241330

331+
332+
HTTP 200 OK
333+
Content-Type: application/json
334+
242335
{
243336
"title": "My New Document Title"
244337
}
245338

246339

247-
Example 4
248-
^^^^^^^^^
340+
Query parameters
341+
^^^^^^^^^^^^^^^^
249342

250-
Code
251-
````
343+
This example appends query parameters to the request's query string.
344+
The response is omitted.
345+
346+
Markup
347+
``````
252348

253349
.. code-block:: rst
254350
@@ -286,11 +382,14 @@ Result
286382
Examples with external sources
287383
------------------------------
288384

289-
Example 1
290-
^^^^^^^^^
385+
The following examples demonstrate the use of external source files.
386+
These files can also be used in tests to ensure their validity.
291387

292-
Code
293-
````
388+
HTTP ``GET``
389+
^^^^^^^^^^^^
390+
391+
Markup
392+
``````
294393

295394
.. code-block:: rst
296395
@@ -305,11 +404,11 @@ Result
305404
:request: ../tests/fixtures/001.request.txt
306405
:response: ../tests/fixtures/001.response.txt
307406

308-
Example 2
309-
^^^^^^^^^
407+
HTTP ``POST``
408+
^^^^^^^^^^^^^
310409

311-
Code
312-
````
410+
Markup
411+
``````
313412

314413
.. code-block:: rst
315414
@@ -324,11 +423,13 @@ Result
324423
:request: ../tests/fixtures/002.request.txt
325424
:response: ../tests/fixtures/002.response.txt
326425

327-
Example 3
328-
^^^^^^^^^
329426

330-
Code
331-
````
427+
HTTP ``PATCH``
428+
^^^^^^^^^^^^^^
429+
430+
431+
Markup
432+
``````
332433

333434
.. code-block:: rst
334435
@@ -350,8 +451,8 @@ Examples with tab libraries
350451
`sphinx-inline-tabs <https://sphinx-inline-tabs.readthedocs.io/en/latest/>`_
351452
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
352453

353-
Code
354-
````
454+
Markup
455+
``````
355456

356457
.. code-block:: rst
357458
@@ -380,6 +481,11 @@ Code
380481
.. http:example-block:: wget
381482
:request: ../tests/fixtures/001.request.txt
382483
484+
.. tab:: plone-client
485+
486+
.. http:example-block:: wget
487+
:request: ../tests/fixtures/001.request.txt
488+
383489
.. tab:: response
384490
385491
.. http:example-block:: response
@@ -413,6 +519,11 @@ Result
413519
.. http:example-block:: wget
414520
:request: ../tests/fixtures/001.request.txt
415521

522+
.. tab:: plone-client
523+
524+
.. http:example-block:: wget
525+
:request: ../tests/fixtures/001.request.txt
526+
416527
.. tab:: response
417528

418529
.. http:example-block:: response
@@ -422,8 +533,8 @@ Result
422533
`sphinx-design <https://sphinx-design.readthedocs.io/en/furo-theme/tabs.html>`_
423534
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
424535

425-
Code
426-
````
536+
Markup
537+
``````
427538

428539
.. code-block:: rst
429540
@@ -454,6 +565,11 @@ Code
454565
.. http:example-block:: wget
455566
:request: ../tests/fixtures/001.request.txt
456567
568+
.. tab-item:: plone-client
569+
570+
.. http:example-block:: wget
571+
:request: ../tests/fixtures/001.request.txt
572+
457573
.. tab-item:: response
458574
459575
.. http:example-block:: response
@@ -489,6 +605,11 @@ Result
489605
.. http:example-block:: wget
490606
:request: ../tests/fixtures/001.request.txt
491607

608+
.. tab-item:: plone-client
609+
610+
.. http:example-block:: wget
611+
:request: ../tests/fixtures/001.request.txt
612+
492613
.. tab-item:: response
493614

494615
.. http:example-block:: response

‎tests/test_directives.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ def test_inline_response_parser():
4848
try:
4949
app.build()
5050
with open(os.path.join(app.outdir, "usage.html")) as fp:
51-
assert fp.read().count("http-example-response") == 5
51+
assert fp.read().count("http-example-response") == 7
5252
finally:
5353
app.cleanup()
5454

0 commit comments

Comments
 (0)