Skip to content

Commit fd87a90

Browse files
committed
docs: clean up RST markup and formatting
Use correct Sphinx version-changed/version-removed directives, normalize code-block languages to "console", convert hyperlink references to anonymous __ syntax, fix indentation and add blank lines between sections for readability. Signed-off-by: Robin Jarry <robin@jarry.cc>
1 parent 2ee1945 commit fd87a90

6 files changed

Lines changed: 83 additions & 57 deletions

File tree

‎docs/api/index.rst‎

Lines changed: 41 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -17,15 +17,17 @@ exposed by the API, refer to the auto-generated OpenAPI documentation at::
1717

1818
where `patchwork.example.com` refers to the URL of your Patchwork instance.
1919

20-
.. versionchanged:: 4.0
20+
.. version-changed:: 4.0
2121

2222
The OpenAPI schema is now auto-generated at runtime and served at
2323
`/api/docs`. Static schema files are no longer shipped.
2424

25-
.. versionchanged:: 4.0
25+
.. version-removed:: 4.0
2626

27-
The XML-RPC API has been removed. Use the REST API with clients like
28-
:program:`git-pw` instead.
27+
The XML-RPC API has been removed. Use the REST API with clients like git-pw__
28+
instead.
29+
30+
__ https://github.com/getpatchwork/git-pw
2931

3032
Getting Started
3133
---------------
@@ -35,23 +37,25 @@ auto-generated documentation at `/api/docs`.
3537

3638
REST APIs run over plain HTTP(S), thus, the API can be interfaced using
3739
applications or libraries that support this widespread protocol. One such
38-
application is `curl`_, which can be used to both retrieve and send information
39-
to the REST API. For example, to get the version of the REST API for a
40-
Patchwork instance hosted at `patchwork.example.com`, run:
41-
42-
.. code-block:: shell
43-
44-
$ curl -s 'https://patchwork.example.com/api/1.4/' | python -m json.tool
45-
{
46-
"bundles": "https://patchwork.example.com/api/1.4/bundles/",
47-
"covers": "https://patchwork.example.com/api/1.4/covers/",
48-
"events": "https://patchwork.example.com/api/1.4/events/",
49-
"patches": "https://patchwork.example.com/api/1.4/patches/",
50-
"people": "https://patchwork.example.com/api/1.4/people/",
51-
"projects": "https://patchwork.example.com/api/1.4/projects/",
52-
"series": "https://patchwork.example.com/api/1.4/series/",
53-
"users": "https://patchwork.example.com/api/1.4/users/"
54-
}
40+
application is curl__, which can be used to both retrieve and send information
41+
to the REST API. For example, to get the version of the REST API for a Patchwork
42+
instance hosted at `patchwork.example.com`, run:
43+
44+
__ https://curl.haxx.se/
45+
46+
.. code-block:: console
47+
48+
$ curl -sL https://patchwork.example.com/api/ | jq
49+
{
50+
"bundles": "https://patchwork.example.com/api/1.4/bundles/",
51+
"covers": "https://patchwork.example.com/api/1.4/covers/",
52+
"events": "https://patchwork.example.com/api/1.4/events/",
53+
"patches": "https://patchwork.example.com/api/1.4/patches/",
54+
"people": "https://patchwork.example.com/api/1.4/people/",
55+
"projects": "https://patchwork.example.com/api/1.4/projects/",
56+
"series": "https://patchwork.example.com/api/1.4/series/",
57+
"users": "https://patchwork.example.com/api/1.4/users/"
58+
}
5559
5660
Tools like `curl` and libraries like `requests` can be used to build anything
5761
from small utilities to full-fledged clients targeting the REST API. For an
@@ -104,33 +108,35 @@ Parameters
104108

105109
For `GET` requests, parameters should be passed as HTTP query string parameters:
106110

107-
.. code-block:: shell
111+
.. code-block:: console
108112
109-
$ curl 'https://patchwork.example.com/api/patches?state=under-review'
113+
$ curl 'https://patchwork.example.com/api/patches?state=under-review'
110114
111115
For `POST` and `PATCH` requests, parameters should be encoded as JSON with
112116
a `Content-Type` of `application/json`:
113117

114-
.. code-block:: shell
118+
.. code-block:: console
115119
116-
$ curl -X PATCH \
117-
--header "Content-Type: application/json" \
118-
--data '{"state":"under-review"}' \
119-
'https://patchwork.example.com/api/patches/123/'
120+
$ curl -X PATCH \
121+
--header "Content-Type: application/json" \
122+
--data '{"state":"under-review"}' \
123+
https://patchwork.example.com/api/patches/123
120124
121125
Authentication
122126
--------------
123127

124128
Patchwork supports authentication using bearer token authentication. To
125-
authenticate, first generate a token from your user profile page, then::
129+
authenticate, first generate a token from your user profile page, then:
130+
131+
.. code-block:: console
132+
133+
$ curl -H "Authorization: Bearer $token" https://patchwork.example.com/api
126134
127-
$ curl -H "Authorization: Bearer ${token}" \
128-
'https://patchwork.example.com/api/'
135+
The legacy `Token` scheme is also accepted for backward compatibility:
129136

130-
The legacy `Token` scheme is also accepted for backward compatibility::
137+
.. code-block:: console
131138
132-
$ curl -H "Authorization: Token ${token}" \
133-
'https://patchwork.example.com/api/'
139+
$ curl -H "Authorization: Token $token" https://patchwork.example.com/api
134140
135141
Not all resources require authentication. Those that do will return
136142
`401 (Unauthorized)` if authentication is not provided.
@@ -144,12 +150,9 @@ can change page using the `?page` parameter and set custom page sizes up to
144150

145151
.. code-block:: shell
146152
147-
$ curl 'https://patchwork.example.com/api/patches?page=2&per_page=100'
153+
$ curl 'https://patchwork.example.com/api/patches?page=2&per_page=100'
148154
149155
The `Link` header includes pagination information::
150156

151157
Link: <https://patchwork.example.com/api/patches?page=3&per_page=100>; rel="next",
152158
<https://patchwork.example.com/api/patches?page=50&per_page=100>; rel="last"
153-
154-
155-
.. _curl: https://curl.haxx.se/

‎docs/deployment/configuration.rst‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,9 @@ Configuration
77
=============
88

99
Patchwork is configured through a TOML file. The default configuration can be
10-
generated with::
10+
generated with:
11+
12+
.. code-block:: console
1113
1214
$ pw config
1315

‎docs/deployment/installation.rst‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ Install PostgreSQL and create a database:
4343
$ sudo -u postgres createuser -d patchwork
4444
$ sudo -u postgres createdb -O patchwork patchwork
4545
46+
4647
SQLite
4748
~~~~~~
4849

@@ -134,10 +135,10 @@ Running Services
134135
Patchwork consists of two long-running services:
135136

136137
`pw http`
137-
The HTTP server exposing the web interface and REST API.
138+
The HTTP server exposing the web interface and REST API.
138139

139140
`pw ingress`
140-
The SMTP daemon that receives emails from your mail transfer agent.
141+
The SMTP daemon that receives emails from your mail transfer agent.
141142

142143
systemd
143144
~~~~~~~
@@ -236,21 +237,22 @@ over SMTP. No shell scripts, no special user accounts, no database grants.
236237
`List-ID` header. Make sure the `-e` (list email) and `-i` (list ID)
237238
values of your project match what your mailing list software produces.
238239

240+
239241
IMAP/POP3
240242
~~~~~~~~~
241243

242244
For simpler setups, you can use a mail retriever like `getmail`__ to download
243245
messages from an inbox and pipe them to Patchwork:
244246

247+
__ http://pyropus.ca/software/getmail/
248+
245249
.. code-block:: ini
246250
247251
[destination]
248252
type = MDA_external
249253
path = /usr/bin/pw
250254
arguments = ("ingress", "--stdin",)
251255
252-
__ http://pyropus.ca/software/getmail/
253-
254256
Manual Import
255257
~~~~~~~~~~~~~
256258

@@ -264,8 +266,6 @@ For one-off imports, `pw ingress` can read from stdin:
264266
The `--list-id` flag can be used to override the `List-ID` header.
265267

266268

267-
.. _deployment-vcs:
268-
269269
(Optional) VCS Integration
270270
--------------------------
271271

‎docs/usage/clients.rst‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
..
44
.. SPDX-License-Identifier: GPL-2.0-or-later
55
6+
67
Clients
78
=======
89

@@ -12,12 +13,12 @@ A number of clients are available for interacting with Patchwork's REST API.
1213
git-pw
1314
------
1415

15-
The :program:`git-pw` application can be used to integrate Patchwork with Git.
16-
The :program:`git-pw` application relies on the REST API and can be used to
17-
list, download and apply series, bundles and individual patches.
16+
The `git-pw` application can be used to integrate Patchwork with Git. The
17+
`git-pw` application relies on the REST API and can be used to list, download
18+
and apply series, bundles and individual patches.
1819

19-
More information on :program:`git-pw`, including installation and usage
20-
instructions, can be found in the `documentation`__ and the `GitHub repo`__.
20+
More information on `git-pw`, including installation and usage instructions, can
21+
be found in the documentation__ and the `GitHub repo`__.
2122

2223
__ https://git-pw.readthedocs.io/
2324
__ https://github.com/getpatchwork/git-pw/
@@ -46,6 +47,6 @@ continuous integration automation server. It monitors the REST API for incoming
4647
patches, applies them on top of an existing git tree, triggers appropriate
4748
builds and test suites, and reports the results back to Patchwork.
4849

49-
Find out more about :program:`snowpatch` at its `GitHub repo`__.
50+
Find out more about `snowpatch` at its `GitHub repo`__.
5051

5152
__ https://github.com/ruscur/snowpatch

‎docs/usage/delegation.rst‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,12 +16,13 @@ configured using the `pw` command line tool.
1616
require configuration of autodelegation rules on a local instance, contact
1717
your Patchwork administrator.
1818

19+
1920
Managing Rules
2021
--------------
2122

2223
Rules are managed using the `pw admin delegate-rule` subcommand.
2324

24-
To list existing rules for a project::
25+
To list existing rules for a project:
2526

2627
$ pw admin delegate-rule list my-project
2728

@@ -33,10 +34,11 @@ To create a new rule::
3334
--path "drivers/net/*" \
3435
--priority 10
3536

36-
To delete a rule::
37+
To delete a rule:
3738

3839
$ pw admin delegate-rule delete 42
3940

41+
4042
Rule Fields
4143
-----------
4244

0 commit comments

Comments
 (0)