Skip to content

Commit 2ee1945

Browse files
committed
docs: set default_role=code for shorter markup
Set default_role=code in the Sphinx configuration so that single backticks render as inline code. Replace all double backtick markup with single backticks throughout the documentation. Signed-off-by: Robin Jarry <robin@jarry.cc>
1 parent 7605dd4 commit 2ee1945

13 files changed

Lines changed: 208 additions & 206 deletions

File tree

‎Makefile‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,7 @@ docs:
6969
-Dversion="$(PATCHWORK_VERSION)" \
7070
-Drelease="$(PATCHWORK_VERSION)" \
7171
-Dtoday="$(DATE)" \
72+
-Ddefault_role=code \
7273
-Dexclude_patterns=_build,.venv \
7374
-Dhtml_theme=sphinx_rtd_theme \
7475
docs docs/_build

‎docs/api/index.rst‎

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

1616
https://patchwork.example.com/api/docs
1717

18-
where ``patchwork.example.com`` refers to the URL of your Patchwork instance.
18+
where `patchwork.example.com` refers to the URL of your Patchwork instance.
1919

2020
.. versionchanged:: 4.0
2121

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

2525
.. versionchanged:: 4.0
2626

@@ -31,13 +31,13 @@ Getting Started
3131
---------------
3232

3333
The easiest way to start experimenting with the API is to visit the
34-
auto-generated documentation at ``/api/docs``.
34+
auto-generated documentation at `/api/docs`.
3535

3636
REST APIs run over plain HTTP(S), thus, the API can be interfaced using
3737
applications or libraries that support this widespread protocol. One such
3838
application is `curl`_, which can be used to both retrieve and send information
3939
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:
40+
Patchwork instance hosted at `patchwork.example.com`, run:
4141

4242
.. code-block:: shell
4343
@@ -61,7 +61,7 @@ Versioning
6161
----------
6262

6363
By default, all requests will receive the latest version of the API: currently
64-
``1.4``:
64+
`1.4`:
6565

6666
.. code-block:: http
6767
@@ -88,29 +88,28 @@ Older API versions will be deprecated and removed over time.
8888
Schema
8989
------
9090

91-
Responses are returned as JSON. Blank fields are returned as ``null``, rather
92-
than being omitted. Timestamps use the ISO 8601 format, times are in UTC::
91+
Responses are returned as JSON. Blank fields are returned as `null`, rather than
92+
being omitted. Timestamps use the ISO 8601 format, times are in UTC::
9393

9494
YYYY-MM-DDTHH:MM:SSZ
9595

9696
Requests should use either query parameters or form-data, depending on the
9797
method.
9898

99-
The auto-generated OpenAPI schema is available at ``/api/docs`` and describes
100-
all endpoints, parameters, and response formats.
99+
The auto-generated OpenAPI schema is available at `/api/docs` and describes all
100+
endpoints, parameters, and response formats.
101101

102102
Parameters
103103
----------
104104

105-
For ``GET`` requests, parameters should be passed as HTTP query string
106-
parameters:
105+
For `GET` requests, parameters should be passed as HTTP query string parameters:
107106

108107
.. code-block:: shell
109108
110109
$ curl 'https://patchwork.example.com/api/patches?state=under-review'
111110
112-
For ``POST`` and ``PATCH`` requests, parameters should be encoded as JSON with
113-
a ``Content-Type`` of ``application/json``:
111+
For `POST` and `PATCH` requests, parameters should be encoded as JSON with
112+
a `Content-Type` of `application/json`:
114113

115114
.. code-block:: shell
116115
@@ -128,26 +127,26 @@ authenticate, first generate a token from your user profile page, then::
128127
$ curl -H "Authorization: Bearer ${token}" \
129128
'https://patchwork.example.com/api/'
130129

131-
The legacy ``Token`` scheme is also accepted for backward compatibility::
130+
The legacy `Token` scheme is also accepted for backward compatibility::
132131

133132
$ curl -H "Authorization: Token ${token}" \
134133
'https://patchwork.example.com/api/'
135134

136135
Not all resources require authentication. Those that do will return
137-
``401 (Unauthorized)`` if authentication is not provided.
136+
`401 (Unauthorized)` if authentication is not provided.
138137

139138
Pagination
140139
----------
141140

142141
Requests that return multiple items are paginated by 30 items by default. You
143-
can change page using the ``?page`` parameter and set custom page sizes up to
144-
250 using the ``?per_page`` parameter:
142+
can change page using the `?page` parameter and set custom page sizes up to
143+
250 using the `?per_page` parameter:
145144

146145
.. code-block:: shell
147146
148147
$ curl 'https://patchwork.example.com/api/patches?page=2&per_page=100'
149148
150-
The ``Link`` header includes pagination information::
149+
The `Link` header includes pagination information::
151150

152151
Link: <https://patchwork.example.com/api/patches?page=3&per_page=100>; rel="next",
153152
<https://patchwork.example.com/api/patches?page=50&per_page=100>; rel="last"

‎docs/deployment/configuration.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,9 @@ generated with::
1414
Configuration files are loaded in the following order, with later files
1515
overriding earlier ones:
1616

17-
1. ``/etc/patchwork.toml``
18-
2. ``patchwork.toml`` (current directory)
19-
3. ``$PATCHWORK_TOML`` (environment variable)
17+
1. `/etc/patchwork.toml`
18+
2. `patchwork.toml` (current directory)
19+
3. `$PATCHWORK_TOML` (environment variable)
2020

2121
Command-line flags take precedence over all configuration files.
2222

‎docs/deployment/installation.rst‎

Lines changed: 29 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Requirements
1515

1616
Patchwork requires:
1717

18-
- The ``pw`` binary (built from source or downloaded from a release)
18+
- The `pw` binary (built from source or downloaded from a release)
1919
- A supported database: PostgreSQL (recommended), MySQL/MariaDB, or SQLite
2020
- A mail transfer agent (e.g. Postfix) for receiving patches
2121
- A reverse proxy (e.g. nginx) for TLS termination (optional but recommended)
@@ -68,7 +68,7 @@ Generate a default configuration file:
6868
6969
$ pw config > /etc/patchwork.toml
7070
71-
Edit ``/etc/patchwork.toml`` to set at least the database URL and the HTTP base
71+
Edit `/etc/patchwork.toml` to set at least the database URL and the HTTP base
7272
URL. See :doc:`configuration` for a full reference of all available settings.
7373

7474
A minimal configuration looks like:
@@ -133,43 +133,43 @@ Running Services
133133

134134
Patchwork consists of two long-running services:
135135

136-
``pw http``
136+
`pw http`
137137
The HTTP server exposing the web interface and REST API.
138138

139-
``pw ingress``
139+
`pw ingress`
140140
The SMTP daemon that receives emails from your mail transfer agent.
141141

142142
systemd
143143
~~~~~~~
144144

145-
The ``make install`` target installs systemd unit files. Enable and start the
145+
The `make install` target installs systemd unit files. Enable and start the
146146
services:
147147

148148
.. code-block:: console
149149
150150
$ sudo systemctl daemon-reload
151151
$ sudo systemctl enable --now pw-http pw-ingress
152152
153-
The unit files are installed to ``/usr/lib/systemd/system/``. To override
154-
settings, use ``systemctl edit``:
153+
The unit files are installed to `/usr/lib/systemd/system`. To override settings,
154+
use `systemctl edit`:
155155

156156
.. code-block:: console
157157
158158
$ sudo systemctl edit pw-http
159159
160160
.. note::
161161

162-
Both services read configuration from ``/etc/patchwork.toml`` by default.
163-
Use the ``PATCHWORK_TOML`` environment variable to specify an alternative
162+
Both services read configuration from `/etc/patchwork.toml` by default.
163+
Use the env:`PATCHWORK_TOML` environment variable to specify an alternative
164164
path.
165165

166166

167167
Reverse Proxy
168168
-------------
169169

170170
A reverse proxy like nginx is recommended for TLS termination and static file
171-
serving. The ``make install`` target installs a default nginx configuration to
172-
``/etc/nginx/conf.d/patchwork.conf``.
171+
serving. The `make install` target installs a default nginx configuration to
172+
`/etc/nginx/conf.d/patchwork.conf`.
173173

174174
A minimal nginx configuration:
175175

@@ -192,28 +192,29 @@ A minimal nginx configuration:
192192
}
193193
194194
195-
.. _deployment-parsemail:
196-
197195
Incoming Email
198196
--------------
199197

200198
Patchwork needs to receive emails from your mailing list. The recommended
201199
approach is to configure your mail transfer agent to forward messages to the
202-
``pw ingress`` SMTP daemon.
200+
`pw ingress` SMTP daemon.
201+
202+
203+
.. _ingress-transport:
203204

204205
Postfix with Transport Maps
205206
~~~~~~~~~~~~~~~~~~~~~~~~~~~
206207

207208
This is the recommended setup. Configure Postfix to route mail for your list
208-
domain to the ``pw ingress`` daemon using transport maps.
209+
domain to the `pw ingress` daemon using transport maps.
209210

210-
Add to ``/etc/postfix/main.cf``:
211+
Add to `/etc/postfix/main.cf`:
211212

212213
.. code-block:: ini
213214
214215
transport_maps = lmdb:/etc/postfix/transport
215216
216-
Create ``/etc/postfix/transport``:
217+
Create `/etc/postfix/transport`:
217218

218219
.. code-block:: bash
219220
@@ -226,14 +227,13 @@ Build the transport map and reload Postfix:
226227
$ sudo postmap /etc/postfix/transport
227228
$ sudo systemctl reload postfix
228229
229-
All mail addressed to ``lists.example.com`` will now be forwarded to
230-
``pw ingress`` over SMTP. No shell scripts, no special user accounts, no
231-
database grants.
230+
All mail addressed to `lists.example.com` will now be forwarded to `pw ingress`
231+
over SMTP. No shell scripts, no special user accounts, no database grants.
232232

233233
.. note::
234234

235-
The ``pw ingress`` daemon matches incoming emails to projects by their
236-
``List-ID`` header. Make sure the ``-e`` (list email) and ``-i`` (list ID)
235+
The `pw ingress` daemon matches incoming emails to projects by their
236+
`List-ID` header. Make sure the `-e` (list email) and `-i` (list ID)
237237
values of your project match what your mailing list software produces.
238238

239239
IMAP/POP3
@@ -254,26 +254,26 @@ __ http://pyropus.ca/software/getmail/
254254
Manual Import
255255
~~~~~~~~~~~~~
256256

257-
For one-off imports, ``pw ingress`` can read from stdin:
257+
For one-off imports, `pw ingress` can read from stdin:
258258

259259
.. code-block:: console
260260
261261
$ pw ingress --stdin < email.eml
262262
$ pw ingress --mbox < archive.mbox
263263
264-
The ``--list-id`` flag can be used to override the ``List-ID`` header.
264+
The `--list-id` flag can be used to override the `List-ID` header.
265265

266266

267267
.. _deployment-vcs:
268268

269269
(Optional) VCS Integration
270270
--------------------------
271271

272-
Patchwork can update patch states automatically when commits are pushed. A
273-
``post-receive`` Git hook can be configured to mark patches as "accepted" when
272+
Patchwork can update patch states automatically when commits are pushed.
273+
A `post-receive` Git hook can be configured to mark patches as "accepted" when
274274
their corresponding commits land in the repository.
275275

276-
Refer to the ``post-receive.hook`` script in the Patchwork source tree for an
276+
Refer to the `post-receive.hook` script in the Patchwork source tree for an
277277
example implementation that uses the REST API.
278278

279279

@@ -287,7 +287,8 @@ confirmations, and inactive users:
287287
288288
$ pw admin gc
289289
290-
A cron job or systemd timer is recommended (e.g. ``/etc/cron.daily/patchwork-gc``):
290+
A cron job or systemd timer is recommended (e.g.
291+
`/etc/cron.daily/patchwork-gc`):
291292

292293
.. code-block:: bash
293294

0 commit comments

Comments
 (0)