Skip to content

Commit e370b09

Browse files
rjarryrjarry
committed
docs: use confval and program directives
Rewrite the configuration reference to use Sphinx confval directives with proper type and default annotations. Rewrite the management commands to use program and option directives for accurate CLI documentation. Add missing webhook and state/tag deletion command entries. Signed-off-by: Robin Jarry <robin@jarry.cc>
1 parent fd87a90 commit e370b09

2 files changed

Lines changed: 610 additions & 135 deletions

File tree

‎docs/deployment/configuration.rst‎

Lines changed: 94 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -26,78 +26,119 @@ Command-line flags take precedence over all configuration files.
2626
Settings Reference
2727
------------------
2828

29-
``[database]``
30-
~~~~~~~~~~~~~~
29+
.. confval:: syslog
30+
:type: bool
31+
:default: `false`
3132

32-
``url``
33-
Database connection URL. Supported schemes:
33+
Redirect logging to syslog instead of stderr.
3434

35-
- ``postgres://user:pass@host/dbname?sslmode=disable``
36-
- ``mysql://user:pass@host/dbname``
37-
- ``sqlite:///path/to/file.db``
35+
.. confval:: [database].url
36+
:type: string
37+
:default: `""`
3838

39-
``auto-sync``
40-
Automatically run pending migrations when the HTTP server starts.
41-
Default: ``false``.
39+
Database connection URL. Supported schemes:
4240

43-
``[http]``
44-
~~~~~~~~~~
41+
- `postgres://user:pass@host/dbname?sslmode=disable`
42+
- `mysql://user:pass@host/dbname`
43+
- `sqlite:///path/to/file.db`
4544

46-
``listen``
47-
HTTP listen address. Default: ``127.0.0.1:8080``.
45+
.. important::
4846

49-
``base-url``
50-
The public base URL of the Patchwork instance, used for generating links in
51-
emails and API responses. Example: ``https://patchwork.example.com``.
47+
The `user` and `pass` values must be URL-encoded. Use the `pw config
48+
url` command to generate valid connection URLs:
5249

53-
``custom-css``
54-
Path to a custom CSS file. It is served after the built-in stylesheet,
55-
allowing you to override any default styles. The file is read once at startup.
50+
.. code-block:: console
5651
57-
``nav-html``
58-
Path to an HTML file whose content is inserted in the page header, after the
59-
navigation bar. Can be used to display a logo, additional links, or a banner.
60-
The file is read once at startup.
52+
$ ./pw config url
53+
Database type (postgres, mysql, sqlite) [postgres]: mysql
54+
Host [localhost]:
55+
Port [3306]:
56+
Database name [patchwork]: patchwork4
57+
Username [patchwork]:
58+
Password: p@tch/w0rk!
6159
62-
``footer-html``
63-
Path to an HTML file whose content is inserted in the page footer. Can be used
64-
for legal notices or organization-specific links. The file is read once at
65-
startup.
60+
url = "mysql://patchwork:p%40tch%2Fw0rk%21@localhost/patchwork4"
6661
67-
``[ingress]``
68-
~~~~~~~~~~~~~
62+
.. confval:: [database].auto-sync
63+
:type: bool
64+
:default: `false`
6965

70-
``listen``
71-
SMTP listen address for the ingress daemon. Default: ``127.0.0.1:2525``.
66+
Automatically run pending migrations when the HTTP server starts.
7267

73-
``[smtp]``
74-
~~~~~~~~~~
68+
.. confval:: [http].listen
69+
:type: string
70+
:default: `"127.0.0.1:8080"`
7571

76-
Outgoing mail configuration for notifications.
72+
HTTP listen address.
7773

78-
``encryption``
79-
SMTP encryption mode. One of ``none``, ``starttls``, ``tls``.
80-
Default: ``none``.
74+
.. confval:: [http].base-url
75+
:type: string
76+
:default: `""`
8177

82-
``host``
83-
SMTP server hostname. Default: ``localhost``.
78+
The public base URL of the Patchwork instance, used for generating links in
79+
emails and API responses. Example: `https://patchwork.example.com`.
8480

85-
``port``
86-
SMTP server port. Default: ``25``.
81+
.. confval:: [http].custom-css
82+
:type: string
83+
:default: `""`
8784

88-
``user``
89-
SMTP authentication username. Leave empty for unauthenticated delivery.
85+
Path to a custom CSS file. It is served after the built-in stylesheet,
86+
allowing you to override any default styles. The file is read once at startup.
9087

91-
``password``
92-
SMTP authentication password.
88+
.. confval:: [http].nav-html
89+
:type: string
90+
:default: `""`
9391

94-
``from``
95-
Sender email address for outgoing notifications.
96-
Default: ``patchwork@localhost``.
92+
Path to an HTML file whose content is inserted in the page header, after the
93+
navigation bar. Can be used to display a logo, additional links, or a banner.
94+
The file is read once at startup.
9795

96+
.. confval:: [http].footer-html
97+
:type: string
98+
:default: `""`
9899

99-
Global Flags
100-
------------
100+
Path to an HTML file whose content is inserted in the page footer. Can be used
101+
for legal notices or organization-specific links. The file is read once at
102+
startup.
101103

102-
``-S``, ``--syslog``
103-
Redirect logging to syslog instead of stderr.
104+
.. confval:: [ingress].listen
105+
:type: string
106+
:default: `"127.0.0.1:2525"`
107+
108+
SMTP listen address for the ingress daemon.
109+
110+
.. confval:: [smtp].encryption
111+
:type: enum (`none`, `starttls`, `tls`)
112+
:default: `none`
113+
114+
SMTP encryption mode.
115+
116+
.. confval:: [smtp].host
117+
:type: string
118+
:default: `"localhost"`
119+
120+
SMTP server hostname.
121+
122+
.. confval:: [smtp].port
123+
:type: int
124+
:default: `25`
125+
126+
SMTP server port.
127+
128+
.. confval:: [smtp].user
129+
:type: string
130+
:default: `""`
131+
132+
SMTP authentication username. Leave empty for unauthenticated delivery.
133+
134+
.. confval:: [smtp].password
135+
:type: string
136+
:default: `""`
137+
138+
SMTP authentication password.
139+
140+
.. confval:: [smtp].from
141+
:type: string
142+
:default: `"patchwork@localhost"`
143+
144+
Sender email address for outgoing notifications.

0 commit comments

Comments
 (0)