Skip to content

Commit e925680

Browse files
stevepiercystevepiercy
committed
Clean up index.rst markup
1 parent 77d8189 commit e925680

1 file changed

Lines changed: 96 additions & 79 deletions

File tree

‎docs/index.rst‎

Lines changed: 96 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,58 @@
1+
==============================================
12
Sphinx directive for RESTful HTTP API examples
23
==============================================
34

4-
sphinxcontrib-httpexample enhances `sphinxcontrib-httpdomain`_, a Sphinx domain extension for describing RESTful HTTP APIs in detail, with a simple call example directive. The new directive provided by this extension generates RESTful HTTP API call examples for different tools from a single HTTP request example.
5+
sphinxcontrib-httpexample is a Sphinx domain extension for describing RESTful HTTP APIs in detail.
6+
It enhances `sphinxcontrib-httpdomain`_ with a simple call example directive.
7+
The directive provided by this extension generates RESTful HTTP API call examples for different tools from a single HTTP request example.
58

6-
The audience for this extension are developers and technical writes documenting their RESTful HTTP APIs. This extension has originally been developed for documenting `plone.restapi`_.
9+
The audience for this extension are developers and technical writers documenting their RESTful HTTP APIs.
10+
This extension was originally developed for documenting `plone.restapi`_.
711

812
.. _sphinxcontrib-httpdomain: https://pythonhosted.org/sphinxcontrib-httpdomain/
9-
.. _plone.restapi: http://plonerestapi.readthedocs.org/
10-
11-
* Configuration:
12-
13-
The URL scheme, either ``http`` or ``https``, used in the generated examples
14-
can be configured with the ``httpexample_scheme`` configuration variable. It
15-
defaults to ``http``.
16-
17-
.. code-block:: python
13+
.. _plone.restapi: https://6.docs.plone.org/plone.restapi/docs/source/index.html
1814

19-
# conf.py
20-
httpexample_scheme = 'https'
2115

22-
* Syntax:
16+
Configuration
17+
=============
18+
The URL scheme, either ``http`` or ``https``, used in the generated examples can be configured with the ``httpexample_scheme`` configuration variable.
19+
It defaults to ``http``.
2320

24-
.. code-block:: rst
21+
.. code-block:: python
2522
26-
.. http:example:: space separated list of tools
27-
:request: ../optional/rel/path/to/plaintext/request
28-
:response: ../optional/rel/path/to/plaintext/response
23+
# conf.py
24+
httpexample_scheme = "https"
2925
30-
Raw plaintext HTTP request example, which is
31-
required only when :request: is not specified.
26+
Syntax
27+
======
28+
.. code-block:: rst
3229
33-
* Example:
30+
.. http:example:: space separated list of tools
31+
:request: ../optional/rel/path/to/plaintext/request
32+
:response: ../optional/rel/path/to/plaintext/response
3433
35-
.. code-block:: rst
34+
Raw plaintext HTTP request example, which is
35+
required only when ``:request:`` is not specified.
3636
37-
.. http:example:: curl wget httpie python-requests
37+
Example
38+
=======
39+
.. code-block:: rst
3840
39-
GET /Plone/front-page HTTP/1.1
40-
Host: localhost:8080
41-
Accept: application/json
42-
Authorization: Basic YWRtaW46YWRtaW4=
41+
.. http:example:: curl wget httpie python-requests
4342
44-
* Rendering:
45-
46-
.. http:example:: curl wget httpie python-requests
47-
48-
GET /plone/folder/my-document?expand=breadcrumbs,navigation HTTP/1.1
43+
GET /Plone/front-page HTTP/1.1
4944
Host: localhost:8080
5045
Accept: application/json
51-
Authorization: Basic YWRtaW46c2VjcmV0
46+
Authorization: Basic YWRtaW46YWRtaW4=
47+
48+
Rendering
49+
=========
50+
.. http:example:: curl wget httpie python-requests
51+
52+
GET /plone/folder/my-document?expand=breadcrumbs,navigation HTTP/1.1
53+
Host: localhost:8080
54+
Accept: application/json
55+
Authorization: Basic YWRtaW46c2VjcmV0
5256

5357

5458
.. code:: javascript
@@ -57,86 +61,99 @@ The audience for this extension are developers and technical writes documenting
5761
const cli = PloneClient.initialize({apiPath: 'http://nohost/plone'});
5862
const { data, status } = cli.getContent({path: '/plone/folder/my-document', expanders: ['breadcrumbs', 'navigation']})
5963
60-
* Compatible with other tab libraries:
6164
62-
`sphinx-inline-tabs <https://sphinx-inline-tabs.readthedocs.io/en/latest/>`_:
65+
Compatibility with other tab libraries
66+
======================================
67+
68+
sphinxcontrib-httpexample is compatible with the following tab libraries.
69+
70+
71+
`sphinx-inline-tabs <https://sphinx-inline-tabs.readthedocs.io/en/latest/>`_
72+
----------------------------------------------------------------------------
6373

64-
.. tab:: http
74+
.. tab:: http
6575

66-
.. http:example-block:: http
67-
:request: ../tests/fixtures/001.request.txt
76+
.. http:example-block:: http
77+
:request: ../tests/fixtures/001.request.txt
6878

69-
.. tab:: curl
79+
.. tab:: curl
7080

71-
.. http:example-block:: curl
72-
:request: ../tests/fixtures/001.request.txt
81+
.. http:example-block:: curl
82+
:request: ../tests/fixtures/001.request.txt
7383
74-
.. tab:: wget
84+
.. tab:: wget
7585

76-
.. http:example-block:: wget
77-
:request: ../tests/fixtures/001.request.txt
86+
.. http:example-block:: wget
87+
:request: ../tests/fixtures/001.request.txt
7888

79-
.. tab:: httpie
89+
.. tab:: httpie
8090

81-
.. http:example-block:: httpie
82-
:request: ../tests/fixtures/001.request.txt
91+
.. http:example-block:: httpie
92+
:request: ../tests/fixtures/001.request.txt
8393

84-
.. tab:: python-requests
94+
.. tab:: python-requests
8595

86-
.. http:example-block:: wget
87-
:request: ../tests/fixtures/001.request.txt
96+
.. http:example-block:: wget
97+
:request: ../tests/fixtures/001.request.txt
8898

89-
.. tab:: response
99+
.. tab:: response
90100

91-
.. http:example-block:: response
92-
:response: ../tests/fixtures/001.response.txt
101+
.. http:example-block:: response
102+
:response: ../tests/fixtures/001.response.txt
93103

94-
`sphinx-design <https://sphinx-design.readthedocs.io/en/furo-theme/tabs.html>`_:
95104

96-
.. tab-set::
105+
`sphinx-design <https://sphinx-design.readthedocs.io/en/furo-theme/tabs.html>`_
106+
-------------------------------------------------------------------------------
97107

98-
.. tab-item:: http
108+
.. tab-set::
99109

100-
.. http:example-block:: http
101-
:request: ../tests/fixtures/001.request.txt
110+
.. tab-item:: http
102111

103-
.. tab-item:: curl
112+
.. http:example-block:: http
113+
:request: ../tests/fixtures/001.request.txt
104114

105-
.. http:example-block:: curl
106-
:request: ../tests/fixtures/001.request.txt
115+
.. tab-item:: curl
107116

108-
.. tab-item:: wget
117+
.. http:example-block:: curl
118+
:request: ../tests/fixtures/001.request.txt
109119

110-
.. http:example-block:: wget
111-
:request: ../tests/fixtures/001.request.txt
120+
.. tab-item:: wget
112121

113-
.. tab-item:: httpie
122+
.. http:example-block:: wget
123+
:request: ../tests/fixtures/001.request.txt
114124

115-
.. http:example-block:: httpie
116-
:request: ../tests/fixtures/001.request.txt
125+
.. tab-item:: httpie
117126

118-
.. tab-item:: python-requests
127+
.. http:example-block:: httpie
128+
:request: ../tests/fixtures/001.request.txt
119129

120-
.. http:example-block:: wget
121-
:request: ../tests/fixtures/001.request.txt
130+
.. tab-item:: python-requests
122131

123-
.. tab-item:: response
132+
.. http:example-block:: wget
133+
:request: ../tests/fixtures/001.request.txt
124134

125-
.. http:example-block:: response
126-
:response: ../tests/fixtures/001.response.txt
135+
.. tab-item:: response
127136

128-
* Supported tools:
137+
.. http:example-block:: response
138+
:response: ../tests/fixtures/001.response.txt
129139

130-
- curl_
131-
- wget_
132-
- httpie_
133-
- python-requests_
140+
141+
Supported tools
142+
===============
143+
144+
- curl_
145+
- wget_
146+
- httpie_
147+
- python-requests_
134148

135149
.. _curl: https://curl.haxx.se/
136150
.. _wget: https://www.gnu.org/software/wget/
137151
.. _httpie: https://httpie.org/
138-
.. _python-requests: http://docs.python-requests.org/
152+
.. _python-requests: https://requests.readthedocs.io/en/stable/
153+
139154

155+
Contents
156+
========
140157
.. toctree::
141158
:maxdepth: 2
142159

0 commit comments

Comments
 (0)