docs: Add a configuration guide

This should simplify matters for folks that don't have much experience
with Django. It also serves to highlight the 'ENABLE_REST_API' option.

A release note is also added to capture the rename of
DEFAULT_PATCHES_PER_PAGE that has occurred during this cycle.

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

diff --git a/docs/deployment/configuration.rst b/docs/deployment/configuration.rst
new file mode 100644 (file)
index 0000000..3474856
--- /dev/null
+++ b/docs/deployment/configuration.rst
@@ -0,0 +1,108 @@
+Configuration
+=============
+
+This document describes the various configuration options available in
+Patchwork. These options can be used for both :doc:`development
+<../development/installation>` and :doc:`deployment <installation>`
+installations.
+
+The ``settings.py`` File
+------------------------
+
+Patchwork is a Django application and, as such, relies on Python-based settings
+files. Refer to the `Django documentation`__ for more information on the
+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/
+
+Patchwork-specific Settings
+---------------------------
+
+Patchwork utilizes a number of Patchwork-only settings in addition to the
+`Django`__ and `Django REST Framework`__ settings.
+
+``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
+
+    This option was previously named ``DEFAULT_PATCHES_PER_PAGE``. It was
+    renamed as cover letters are now supported also.
+
+``CONFIRMATION_VALIDITY_DAYS``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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.
+
+``NOTIFICATION_FROM_EMAIL``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The email address that notification emails should be sent from.
+
+``ENABLE_XMLRPC``
+~~~~~~~~~~~~~~~~~
+
+Enable the :doc:`XML-RPC API <../api/xmlrpc>`.
+
+``ENABLE_REST_API``
+~~~~~~~~~~~~~~~~~~~
+
+Enable the :doc:`REST API <../api/rest>`.
+
+.. versionadded:: 2.0
+
+``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
+
+``COMPAT_REDIR``
+~~~~~~~~~~~~~~~~
+
+Enable redirections of URLs from previous versions of Patchwork.
+
+.. 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)
+
+__ https://docs.djangoproject.com/en/1.8/ref/settings/
+__ http://www.django-rest-framework.org/api-guide/settings/

diff --git a/docs/deployment/installation.rst b/docs/deployment/installation.rst
index 3b3636d89b88e27b1e5e88461fc7647ccf83c1d1..1b472233ebae22b60a254276f91102081e533cc7 100644 (file)
--- a/docs/deployment/installation.rst
+++ b/docs/deployment/installation.rst
@@ -4,7 +4,7 @@ Installation
 This document describes the necessary steps to configure Patchwork in a
 production environment. This requires a significantly "harder" deployment than
 the one used for development. If you are interested in developing Patchwork,
-refer to the **development guide** instead.
+refer to the :doc:`development guide <../development/installation>` instead.
 
 This document describes a two-node installation of Patchwork, consisting of a
 database sever and an application server. It should be possible to combine
@@ -187,6 +187,8 @@ corresponding distro package for each of these requirements. For example:
 
 __ https://pkgs.org/
 
+.. _deployment-settings:
+
 Configure Patchwork
 ~~~~~~~~~~~~~~~~~~~
 
@@ -409,6 +411,8 @@ at boot:
 __ https://uwsgi-docs.readthedocs.io/en/latest/Systemd.html
 __ https://uwsgi-docs.readthedocs.io/en/latest/Upstart.html
 
+.. _deployment-final-steps:
+
 Final Steps
 ~~~~~~~~~~~
 

diff --git a/docs/index.rst b/docs/index.rst
index 29f2c9d31ad1a537f8423c37d3995a5bc5303e6e..623b683ae3e8ef586bb23842d0c8b1ff2e6dc656 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -36,6 +36,7 @@ of community projects.
    :caption: Deployment Documentation
 
    deployment/installation
+   deployment/configuration
    deployment/upgrading
 
 .. _development-docs:

diff --git a/releasenotes/notes/rename-default_patches_per_page-4ff3ad6dc1c82af7.yaml b/releasenotes/notes/rename-default_patches_per_page-4ff3ad6dc1c82af7.yaml
new file mode 100644 (file)
index 0000000..0d3b985
--- /dev/null
+++ b/releasenotes/notes/rename-default_patches_per_page-4ff3ad6dc1c82af7.yaml
@@ -0,0 +1,6 @@
+---
+upgrade:
+  - |
+    The ``DEFAULT_PATCHES_PER_PAGE`` has been renamed as
+    ``DEFAULT_ITEMS_PER_PAGE`` as it is now possible to list cover letters in
+    addition to patches.