docs: add Sphinx documentation for 4.0.0

Port the documentation from the Django-based patchwork, rewritten
for the Go binary. Cover installation with postfix transport
maps, configuration reference, management commands, a migration
guide from Django to Go with command and settings mappings, and
4.0.0 release notes via reno.

Signed-off-by: Robin Jarry <robin@jarry.cc>

Author: rjarry

.gitignore

@@ -1,3 +1,5 @@
 /patchwork.toml
 /pw
 *_templ.go
+/docs/.venv
+/docs/_build

Makefile

@@ -34,11 +34,22 @@ install: pw
 	install -Dm644 etc/nginx.conf $(DESTDIR)$(sysconfdir)/nginx/conf.d/patchwork.conf
 	$(DESTDIR)$(prefix)/bin/pw config > $(DESTDIR)$(sysconfdir)/patchwork.toml
 
+PYTHON ?= python3
+
+.PHONY: docs
+docs:
+	$Q if ! [ -x docs/.venv/bin/sphinx-build ]; then \
+		set -xe && \
+		$(PYTHON) -m venv docs/.venv && \
+		docs/.venv/bin/pip install -q -r docs/requirements.txt; \
+	fi
+	docs/.venv/bin/sphinx-build -b html docs docs/_build
+
 import_reviser ?= github.com/incu6us/goimports-reviser/v3@v3.12.6
 import_reviser_flags ?= -rm-unused -project-name github.com/getpatchwork/patchwork
 gofumpt ?= mvdan.cc/gofumpt@v0.9.2
 golangci_lint ?= github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.12.2
-license_exclude = ':!:*.md' ':!:*.asc' ':!:CONTRIBUTORS' ':!:LICENSE' ':!:.*' ':!:go.mod' ':!:go.sum' ':!:pkg/mail/testdata'
+license_exclude = ':!:*.md' ':!:*.asc' ':!:*.yaml' ':!:docs/requirements.txt' ':!:*.service' ':!:CONTRIBUTORS' ':!:LICENSE' ':!:.*' ':!:go.mod' ':!:go.sum' ':!:pkg/mail/testdata'
 
 .PHONY: test
 test:

docs/api/index.rst

@@ -0,0 +1,153 @@
+.. Patchwork - automated patch tracking system
+.. Copyright (C) The Patchwork Contributors (see CONTRIBUTORS)
+..
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+The REST API
+============
+
+Patchwork provides a REST API. This API can be used to retrieve and modify
+information about patches, projects and more.
+
+This guide provides an overview of how one can interact with the REST API. For
+detailed information on type and response format of the various resources
+exposed by the API, refer to the auto-generated OpenAPI documentation at::
+
+    https://patchwork.example.com/api/docs
+
+where ``patchwork.example.com`` refers to the URL of your Patchwork instance.
+
+.. versionchanged:: 4.0
+
+   The OpenAPI schema is now auto-generated at runtime and served at
+   ``/api/docs``. Static schema files are no longer shipped.
+
+.. versionchanged:: 4.0
+
+   The XML-RPC API has been removed. Use the REST API with clients like
+   :program:`git-pw` instead.
+
+Getting Started
+---------------
+
+The easiest way to start experimenting with the API is to visit the
+auto-generated documentation at ``/api/docs``.
+
+REST APIs run over plain HTTP(S), thus, the API can be interfaced using
+applications or libraries that support this widespread protocol. One such
+application is `curl`_, which can be used to both retrieve and send information
+to the REST API. For example, to get the version of the REST API for a
+Patchwork instance hosted at ``patchwork.example.com``, run:
+
+.. code-block:: shell
+
+    $ curl -s 'https://patchwork.example.com/api/1.4/' | python -m json.tool
+    {
+        "bundles": "https://patchwork.example.com/api/1.4/bundles/",
+        "covers": "https://patchwork.example.com/api/1.4/covers/",
+        "events": "https://patchwork.example.com/api/1.4/events/",
+        "patches": "https://patchwork.example.com/api/1.4/patches/",
+        "people": "https://patchwork.example.com/api/1.4/people/",
+        "projects": "https://patchwork.example.com/api/1.4/projects/",
+        "series": "https://patchwork.example.com/api/1.4/series/",
+        "users": "https://patchwork.example.com/api/1.4/users/"
+    }
+
+Tools like `curl` and libraries like `requests` can be used to build anything
+from small utilities to full-fledged clients targeting the REST API. For an
+overview of existing API clients, refer to :doc:`/usage/clients`.
+
+Versioning
+----------
+
+By default, all requests will receive the latest version of the API: currently
+``1.4``:
+
+.. code-block:: http
+
+    GET /api HTTP/1.1
+
+You should explicitly request this version through the URL to prevent API
+changes breaking your application:
+
+.. code-block:: http
+
+    GET /api/1.4 HTTP/1.1
+
+Older API versions will be deprecated and removed over time.
+
+.. csv-table::
+   :header: "API Version", "Supported?"
+
+   1.0, yes
+   1.1, yes
+   1.2, yes
+   1.3, yes
+   1.4, yes
+
+Schema
+------
+
+Responses are returned as JSON. Blank fields are returned as ``null``, rather
+than being omitted. Timestamps use the ISO 8601 format, times are in UTC::
+
+    YYYY-MM-DDTHH:MM:SSZ
+
+Requests should use either query parameters or form-data, depending on the
+method.
+
+The auto-generated OpenAPI schema is available at ``/api/docs`` and describes
+all endpoints, parameters, and response formats.
+
+Parameters
+----------
+
+For ``GET`` requests, parameters should be passed as HTTP query string
+parameters:
+
+.. code-block:: shell
+
+    $ curl 'https://patchwork.example.com/api/patches?state=under-review'
+
+For ``POST`` and ``PATCH`` requests, parameters should be encoded as JSON with
+a ``Content-Type`` of ``application/json``:
+
+.. code-block:: shell
+
+    $ curl -X PATCH \
+      --header "Content-Type: application/json" \
+      --data '{"state":"under-review"}' \
+      'https://patchwork.example.com/api/patches/123/'
+
+Authentication
+--------------
+
+Patchwork supports authentication using basic authentication (username and
+password) or token authentication (recommended).
+
+To authenticate with a token, first obtain one from your profile page, then::
+
+    $ curl -H "Authorization: Token ${token}" \
+        'https://patchwork.example.com/api/'
+
+Not all resources require authentication. Those that do will return
+``404 (Not Found)`` if authentication is not provided.
+
+Pagination
+----------
+
+Requests that return multiple items are paginated by 30 items by default. You
+can change page using the ``?page`` parameter and set custom page sizes up to
+250 using the ``?per_page`` parameter:
+
+.. code-block:: shell
+
+    $ curl 'https://patchwork.example.com/api/patches?page=2&per_page=100'
+
+The ``Link`` header includes pagination information::
+
+    Link: <https://patchwork.example.com/api/patches?page=3&per_page=100>; rel="next",
+      <https://patchwork.example.com/api/patches?page=50&per_page=100>; rel="last"
+
+
+.. _curl: https://curl.haxx.se/

docs/conf.py

@@ -0,0 +1,22 @@
+# Patchwork - automated patch tracking system
+# Copyright (C) The Patchwork Contributors (see CONTRIBUTORS)
+#
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+extensions = [
+    "reno.sphinxext",
+]
+
+templates_path = []
+master_doc = "index"
+
+project = "Patchwork"
+copyright = "The Patchwork Contributors"
+author = "The Patchwork Contributors"
+
+version = "4.0"
+release = "4.0.0"
+
+exclude_patterns = ["_build", ".venv"]
+
+html_theme = "sphinx_rtd_theme"

docs/deployment/configuration.rst

@@ -0,0 +1,93 @@
+.. Patchwork - automated patch tracking system
+.. Copyright (C) The Patchwork Contributors (see CONTRIBUTORS)
+..
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+Configuration
+=============
+
+Patchwork is configured through a TOML file. The default configuration can be
+generated with::
+
+    $ pw config
+
+Configuration files are loaded in the following order, with later files
+overriding earlier ones:
+
+1. ``/etc/patchwork.toml``
+2. ``patchwork.toml`` (current directory)
+3. ``$PATCHWORK_TOML`` (environment variable)
+
+Command-line flags take precedence over all configuration files.
+
+
+Settings Reference
+------------------
+
+``[database]``
+~~~~~~~~~~~~~~
+
+``url``
+  Database connection URL. Supported schemes:
+
+  - ``postgres://user:pass@host/dbname?sslmode=disable``
+  - ``mysql://user:pass@host/dbname``
+  - ``sqlite:///path/to/file.db``
+
+``auto-sync``
+  Automatically run pending migrations when the HTTP server starts.
+  Default: ``false``.
+
+``[http]``
+~~~~~~~~~~
+
+``listen``
+  HTTP listen address. Default: ``127.0.0.1:8080``.
+
+``base-url``
+  The public base URL of the Patchwork instance, used for generating links in
+  emails and API responses. Example: ``https://patchwork.example.com``.
+
+``[ingress]``
+~~~~~~~~~~~~~
+
+``listen``
+  SMTP listen address for the ingress daemon. Default: ``127.0.0.1:2525``.
+
+``max-message-size``
+  Maximum email message size in bytes. Default: ``10485760`` (10 MB).
+
+``max-recipients``
+  Maximum number of recipients per message. Default: ``100``.
+
+``[smtp]``
+~~~~~~~~~~
+
+Outgoing mail configuration for notifications.
+
+``transport``
+  SMTP encryption mode. One of ``none``, ``starttls``, ``tls``.
+  Default: ``none``.
+
+``host``
+  SMTP server hostname. Default: ``localhost``.
+
+``port``
+  SMTP server port. Default: ``25``.
+
+``user``
+  SMTP authentication username. Leave empty for unauthenticated delivery.
+
+``password``
+  SMTP authentication password.
+
+``from``
+  Sender email address for outgoing notifications.
+  Default: ``patchwork@localhost``.
+
+
+Global Flags
+------------
+
+``-S``, ``--syslog``
+  Redirect logging to syslog instead of stderr.

docs/deployment/index.rst

@@ -0,0 +1,16 @@
+.. Patchwork - automated patch tracking system
+.. Copyright (C) The Patchwork Contributors (see CONTRIBUTORS)
+..
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+Deployment
+==========
+
+.. toctree::
+   :maxdepth: 2
+
+   installation
+   configuration
+   management
+   upgrading
+   migration