docs: Rework configuration document

- Remove some newlines between terms and definitions that were causing
  the latter to be rendered as blockquotes instead
- Order list of settings alphabetically
- Update URLs to use latest version of Django we support

Signed-off-by: Stephen Finucane <stephen@that.guru>

diff --git a/docs/deployment/configuration.rst b/docs/deployment/configuration.rst
index 30a1703541b5138a46fdb32ed56a9483d437c0c9..a71dd3f4bb570b5358f7b0d83b1572233a5f2fd4 100644 (file)
--- a/docs/deployment/configuration.rst
+++ b/docs/deployment/configuration.rst
@@ -16,21 +16,18 @@ general format.
 Patchwork provides three settings files:
 
 ``base.py``
-
   A base settings file that should not be used directly.
 
 ``dev.py``
-
   A settings file for development use. **This file is horribly insecure and
   must not be used in production**.
 
 ``production.example.py``
-
   A sample settings file for production use. This will likely require some
   heavy customization. The :ref:`deployment guide <deployment-settings>`
   provides more information.
 
-__ https://docs.djangoproject.com/en/1.8/topics/settings/
+__ https://docs.djangoproject.com/en/2.2/topics/settings/
 
 Patchwork-specific Settings
 ---------------------------
@@ -38,7 +35,7 @@ Patchwork-specific Settings
 Patchwork utilizes a number of Patchwork-only settings in addition to the
 `Django`__ and `Django REST Framework`__ settings.
 
-__ https://docs.djangoproject.com/en/1.8/ref/settings/
+__ https://docs.djangoproject.com/en/2.2/ref/settings/
 __ http://www.django-rest-framework.org/api-guide/settings/
 
 ``ADMINS_HIDE``
@@ -51,18 +48,10 @@ If True, the details in `ADMINS`__ will be hidden from the *About* page
 
 __ https://docs.djangoproject.com/en/2.2/ref/settings/#admins
 
-``DEFAULT_ITEMS_PER_PAGE``
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The default number of items to display in the list pages for a project
-(``/project/{projectID}/list``) or bundle (``/bundle/{userID}/{bundleName}``).
-
-This is customizable on a per-user basis from the user configuration page.
-
-.. versionchanged:: 2.0
+``COMPAT_REDIR``
+~~~~~~~~~~~~~~~~
 
-    This option was previously named ``DEFAULT_PATCHES_PER_PAGE``. It was
-    renamed as cover letters are now supported also.
+Enable redirections of URLs from previous versions of Patchwork.
 
 ``CONFIRMATION_VALIDITY_DAYS``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -71,22 +60,18 @@ The number of days to consider an account confirmation request valid. After
 this interval, the :ref:`cron management command <deployment-final-steps>` will
 delete the request.
 
-``NOTIFICATION_DELAY_MINUTES``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The number of minutes to wait before sending any notifications to a user. An
-notification generated during this time are gathered into a single digest
-email, ensuring users are not spammed with emails from Patchwork.
+``DEFAULT_ITEMS_PER_PAGE``
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-``NOTIFICATION_FROM_EMAIL``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The default number of items to display in the list pages for a project
+(``/project/{projectID}/list``) or bundle (``/bundle/{userID}/{bundleName}``).
 
-The email address that notification emails should be sent from.
+This is customizable on a per-user basis from the user configuration page.
 
-``ENABLE_XMLRPC``
-~~~~~~~~~~~~~~~~~
+.. versionchanged:: 2.0
 
-Enable the :doc:`XML-RPC API <../api/xmlrpc>`.
+    This option was previously named ``DEFAULT_PATCHES_PER_PAGE``. It was
+    renamed as cover letters are now supported also.
 
 ``ENABLE_REST_API``
 ~~~~~~~~~~~~~~~~~~~
@@ -95,13 +80,19 @@ Enable the :doc:`REST API <../api/rest/index>`.
 
 .. versionadded:: 2.0
 
-``REST_RESULTS_PER_PAGE``
-~~~~~~~~~~~~~~~~~~~~~~~~~
+``ENABLE_XMLRPC``
+~~~~~~~~~~~~~~~~~
 
-The number of items to include in REST API responses by default. This can be
-overridden by the ``per_page`` parameter for some endpoints.
+Enable the :doc:`XML-RPC API <../api/xmlrpc>`.
 
-.. versionadded:: 2.0
+.. TODO(stephenfin) Deprecate this in favor of SECURE_SSL_REDIRECT
+
+``FORCE_HTTPS_LINKS``
+~~~~~~~~~~~~~~~~~~~~~
+
+Force use of ``https://`` links instead of guessing the scheme based on current
+access. This is useful if SSL protocol is terminated upstream of the server
+(e.g. at the load balancer)
 
 ``MAX_REST_RESULTS_PER_PAGE``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -111,17 +102,22 @@ the ``per_page`` parameter.
 
 .. versionadded:: 2.2
 
-``COMPAT_REDIR``
-~~~~~~~~~~~~~~~~
+``NOTIFICATION_DELAY_MINUTES``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Enable redirections of URLs from previous versions of Patchwork.
+The number of minutes to wait before sending any notifications to a user. An
+notification generated during this time are gathered into a single digest
+email, ensuring users are not spammed with emails from Patchwork.
 
-.. TODO(stephenfin) Deprecate this in favor of SECURE_SSL_REDIRECT
+``NOTIFICATION_FROM_EMAIL``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-``FORCE_HTTPS_LINKS``
-~~~~~~~~~~~~~~~~~~~~~
+The email address that notification emails should be sent from.
 
-Force use of ``https://`` links instead of guessing the scheme based on current
-access. This is useful if SSL protocol is terminated upstream of the server
-(e.g. at the load balancer)
+``REST_RESULTS_PER_PAGE``
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
+The number of items to include in REST API responses by default. This can be
+overridden by the ``per_page`` parameter for some endpoints.
+
+.. versionadded:: 2.0