Add new documentation on Zulip settings system.

Fixes: #962.

docs/code-contribution-checklist.rst

@@ -18,6 +18,7 @@ the tips below.
    testing
    logging
    mypy
+   settings
    front-end-build-process
    queuing
    schema-migrations

docs/settings.md

@@ -0,0 +1,120 @@
+# Zulip settings
+
+The page documents the Zulip settings system, and hopefully should
+help you decide how to correctly implement new settings you're adding
+to Zulip.  We have two types of administrative settings in Zulip:
+server settings (which are set via configuration files are apply to
+the whole Zulip installation), and realm settings (which are usually
+set via the /#administration page in the Zulip web application) and
+apply to a single Zulip realm/team (which for most Zulip servers is
+the only realm on the server).
+
+## Server settings
+
+Zulip uses the [Django settings
+system](https://docs.djangoproject.com/en/1.9/topics/settings/), which
+means that the settings files are Python programs that set a lot of
+variables with all-capital names like EMAIL_GATEWAY_PATTERN.  You can
+access these anywhere in the Zulip Django code using e.g.:
+
+```
+from django.conf import settings
+print(settings.EMAIL_GATEWAY_PATTERN)
+```
+
+Additionally, if you need to access a Django setting in a shell
+script (or just on the command line for debugging), you can use e.g.:
+
+```
+$ ./scripts/get-django-setting EMAIL_GATEWAY_PATTERN
+%s@localhost:9991
+```
+
+Zulip has separated those settings that we expect a system
+administrator to change (with nice documentation) from the ~1000 lines
+of settings needed by the Zulip Django app.  As a result, there are a
+few files involved in the Zulip settings for server administrations:
+
+* `/etc/zulip/settings.py` (generated from
+  `zproject/local_settings_template.py`) is the main system
+  administration facing settings file for Zulip.  It contains all the
+  server-specific settings, such as how to send outgoing email, the
+  hostname of the Postgres database, etc., but does not contain any
+  secrets (e.g. passwords, secret API keys, cryptographic keys, etc.).
+
+* `/etc/zulip/zulip-secrets.conf` (generated by
+  `scripts/setup/generate-secrets.py` as part of installation)
+  contains secrets used by the Zulip installation.  These are read
+  using the standard Python `ConfigParser`, and accessed in
+  `zproject/settings.py` by the `get_secret` function.
+
+* `zproject/settings.py` is the main Django settings file for Zulip.
+  It contains all the settings that are constant for all Zulip
+  installations (e.g. configuration for logging, static assets,
+  middleware, etc.), as well as default values for the settings the
+  user would set in `/etc/zulip/settings.py` (you can look at the
+  `DEFAULT_SETTINGS` dictionary to easily review the settings
+  available).  `zproject/settings.py` has a line `from local_settings
+  import *`, which has the effect of importing
+  `/etc/zulip/settings.py`.
+
+Additionally, we have two files used only in development:
+
+* `zproject/dev_settings.py` has the settings for the Zulip development
+  environment; it mostly just imports local_settings_template.py.
+
+* `zproject/test_settings.py` has the (default) settings used for the
+  Zulip tests (both backend and Casper), which are applied on top of
+  the development environment settings.
+
+When adding a new server setting to Zulip, you will typically add it
+in two or three places:
+
+* In DEFAULT_SETTINGS in `zproject/settings.py`, with a default value
+  for production environments.
+
+* In an appropriate section of `zproject/local_settings_template.py`,
+  with documentation in the comments explaining the settings's
+  purpose and effect.
+
+* Possibly also `zproject/dev_settings.py`, if the desired value of
+  the setting for Zulip development environments is different from the
+  default for production (and similarly for `zproject/test_settings.py`).
+
+Most settings should be enabled in the development environment, to
+maximize convenience of testing all of Zulip's features; they should
+be enabled by default in production if we expect most Zulip sites to
+want those settings.
+
+#### Testing non-default settings
+
+You can write tests for settings using e.g. `with
+self.settings(GOOGLE_CLIENT_ID=None)`.  However, this only works for
+settings which are checked at runtime, not settings which are only
+accessed in initialization of Django (or Zulip) internals
+(e.g. `DATABASES`).  See the [Django docs on overriding settings in
+tests][django-test-settings] for more details.
+
+[django-test-settings]: https://docs.djangoproject.com/en/1.9/topics/testing/tools/#overriding-settings
+
+## Realm settings
+
+Realm settings are preferred for any configuration that is a matter of
+organizational policy (as opposed to technical capabilities of the
+server).  As a result, configuration options for user-facing
+functionality is almost always added as a new realm setting, not a
+server setting.  The [new feature tutorial][doc-newfeat] documents the
+process for adding a new realm setting to Zulip.
+
+So for example, the following server settings will eventually be
+replaced with realm settings:
+
+* NAME_CHANGES_DISABLED
+* INLINE_IMAGE_PREVIEW
+* ENABLE_GRAVATAR
+* Which authentication methods are allowed should probably appear in
+  both places; in server settings indicating the capabilities of the
+  server, and in the realm settings indicating which methods the realm
+  administrator wants to allow users to login with.
+
+[doc-newfeat]: http://zulip.readthedocs.io/en/latest/new-feature-tutorial.html

zproject/local_settings_template.py

@@ -1,5 +1,8 @@
-# Settings for Zulip Voyager
-
+# Zulip Settings intended to be set by a system administrator.
+#
+# See http://zulip.readthedocs.io/en/latest/settings.html for
+# detailed technical documentation on the Zulip settings system.
+#
 ### MANDATORY SETTINGS
 #
 # These settings MUST be set in production. In a development environment,

zproject/settings.py

@@ -7,6 +7,9 @@ from __future__ import absolute_import
 # for the Zulip Django app.
 # * settings.py imports local_settings.py, and any site-specific configuration
 # belongs there.  The template for local_settings.py is local_settings_template.py
+#
+# See http://zulip.readthedocs.io/en/latest/settings.html for more information
+#
 ########################################################################
 import os
 import platform