Fixed #14633 - Organized settings reference docs and added a topical index.

Thanks Gabriel Hurley for the original idea
and adamv for the draft patch.

5 files changed, 36 insertions, 270 deletions

diff --git a/docs/ref/contrib/comments/index.txt b/docs/ref/contrib/comments/index.txt
index 8275092d2f..d4e967b4b2 100644
--- a/docs/ref/contrib/comments/index.txt
+++ b/docs/ref/contrib/comments/index.txt
@@ -34,7 +34,8 @@ To get started using the ``comments`` app, follow these steps:
 #. Use the `comment template tags`_ below to embed comments in your
    templates.
 
-You might also want to examine :doc:`/ref/contrib/comments/settings`.
+You might also want to examine :ref:`the available settings
+<settings-comments>`.
 
 Comment template tags
 =====================
@@ -335,6 +336,13 @@ output the CSRF token and cookie.
 
 .. _honeypot: http://en.wikipedia.org/wiki/Honeypot_(computing)
 
+
+Configuration
+=============
+
+See :ref:`comment settings <settings-comments>`.
+
+
 More information
 ================
 
@@ -342,7 +350,6 @@ More information
    :maxdepth: 1
 
    models
-   settings
    signals
    custom
    forms
diff --git a/docs/ref/contrib/comments/settings.txt b/docs/ref/contrib/comments/settings.txt
deleted file mode 100644
index 1f1aecafd4..0000000000
--- a/docs/ref/contrib/comments/settings.txt
+++ /dev/null
@@ -1,33 +0,0 @@
-================
-Comment settings
-================
-
-These settings configure the behavior of the comments framework:
-
-.. setting:: COMMENTS_HIDE_REMOVED
-
-COMMENTS_HIDE_REMOVED
----------------------
-
-If ``True`` (default), removed comments will be excluded from comment
-lists/counts (as taken from template tags). Otherwise, the template author is
-responsible for some sort of a "this comment has been removed by the site staff"
-message.
-
-.. setting:: COMMENT_MAX_LENGTH
-
-COMMENT_MAX_LENGTH
-------------------
-
-The maximum length of the comment field, in characters. Comments longer than
-this will be rejected. Defaults to 3000.
-
-.. setting:: COMMENTS_APP
-
-COMMENTS_APP
-------------
-
-An app which provides :doc:`customization of the comments framework
-</ref/contrib/comments/custom>`.  Use the same dotted-string notation
-as in :setting:`INSTALLED_APPS`.  Your custom :setting:`COMMENTS_APP`
-must also be listed in :setting:`INSTALLED_APPS`.
diff --git a/docs/ref/contrib/csrf.txt b/docs/ref/contrib/csrf.txt
index 42a41c4bfc..3ad16e2f97 100644
--- a/docs/ref/contrib/csrf.txt
+++ b/docs/ref/contrib/csrf.txt
@@ -488,60 +488,10 @@ developers of other reusable apps that want the same guarantees also use the
 Settings
 ========
 
-A number of settings can be used to control Django's CSRF behavior.
+A number of settings can be used to control Django's CSRF behavior:
 
-CSRF_COOKIE_DOMAIN
-------------------
-
-Default: ``None``
-
-The domain to be used when setting the CSRF cookie.  This can be useful for
-easily allowing cross-subdomain requests to be excluded from the normal cross
-site request forgery protection.  It should be set to a string such as
-``".example.com"`` to allow a POST request from a form on one subdomain to be
-accepted by a view served from another subdomain.
-
-Please note that, with or without use of this setting, this CSRF protection
-mechanism is not safe against cross-subdomain attacks -- see `Limitations`_.
-
-CSRF_COOKIE_NAME
-----------------
-
-Default: ``'csrftoken'``
-
-The name of the cookie to use for the CSRF authentication token. This can be
-whatever you want.
-
-CSRF_COOKIE_PATH
-----------------
-
-Default: ``'/'``
-
-The path set on the CSRF cookie. This should either match the URL path of your
-Django installation or be a parent of that path.
-
-This is useful if you have multiple Django instances running under the same
-hostname. They can use different cookie paths, and each instance will only see
-its own CSRF cookie.
-
-CSRF_COOKIE_SECURE
-------------------
-
-Default: ``False``
-
-Whether to use a secure cookie for the CSRF cookie. If this is set to ``True``,
-the cookie will be marked as "secure," which means browsers may ensure that the
-cookie is only sent under an HTTPS connection.
-
-CSRF_FAILURE_VIEW
------------------
-
-Default: ``'django.views.csrf.csrf_failure'``
-
-A dotted path to the view function to be used when an incoming request
-is rejected by the CSRF protection.  The function should have this signature::
-
-  def csrf_failure(request, reason="")
-
-where ``reason`` is a short message (intended for developers or logging, not for
-end users) indicating the reason the request was rejected.
+* :setting:`CSRF_COOKIE_DOMAIN`
+* :setting:`CSRF_COOKIE_NAME`
+* :setting:`CSRF_COOKIE_PATH`
+* :setting:`CSRF_COOKIE_SECURE`
+* :setting:`CSRF_FAILURE_VIEW`
diff --git a/docs/ref/contrib/messages.txt b/docs/ref/contrib/messages.txt
index 661d7f2103..40f7d41ceb 100644
--- a/docs/ref/contrib/messages.txt
+++ b/docs/ref/contrib/messages.txt
@@ -78,8 +78,8 @@ Django provides three built-in storage classes:
 
 :class:`~django.contrib.messages.storage.fallback.FallbackStorage` is the
 default storage class. If it isn't suitable to your needs, you can select
-another storage class by setting `MESSAGE_STORAGE`_ to its full import path,
-for example::
+another storage class by setting setting:`MESSAGE_STORAGE` to its full import
+path, for example::
 
     MESSAGE_STORAGE = 'django.contrib.messages.storage.cookie.CookieStorage'
 
@@ -87,6 +87,8 @@ To write your own storage class, subclass the ``BaseStorage`` class in
 ``django.contrib.messages.storage.base`` and implement the ``_get`` and
 ``_store`` methods.
 
+.. _message-level:
+
 Message levels
 --------------
 
@@ -108,7 +110,7 @@ Constant    Purpose
 ``ERROR``   An action was **not** successful or some other failure occurred
 =========== ========
 
-The `MESSAGE_LEVEL`_ setting can be used to change the minimum recorded level
+The :setting:`MESSAGE_LEVEL` setting can be used to change the minimum recorded level
 (or it can be `changed per request`_). Attempts to add messages of a level less
 than this will be ignored.
 
@@ -136,7 +138,7 @@ Level Constant  Tag
 ==============  ===========
 
 To change the default tags for a message level (either built-in or custom),
-set the `MESSAGE_TAGS`_ setting to a dictionary containing the levels
+set the :setting:`MESSAGE_TAGS` setting to a dictionary containing the levels
 you wish to change. As this extends the default tags, you only need to provide
 tags for the levels you wish to override::
 
@@ -168,6 +170,8 @@ used tags (which are usually represented as HTML classes for the message)::
     messages.warning(request, 'Your account expires in three days.')
     messages.error(request, 'Document deleted.')
 
+.. _message-displaying:
+
 Displaying messages
 -------------------
 
@@ -216,7 +220,7 @@ Level Constant  Value
 ==============  =====
 
 If you need to identify the custom levels in your HTML or CSS, you need to
-provide a mapping via the `MESSAGE_TAGS`_ setting.
+provide a mapping via the :setting:`MESSAGE_TAGS` setting.
 
 .. note::
    If you are creating a reusable application, it is recommended to use
@@ -316,80 +320,10 @@ window/tab will have its own browsing context.
 Settings
 ========
 
-A few :doc:`Django settings </ref/settings>` give you control over message
+A few :ref:`settings<settings-messages>` give you control over message
 behavior:
 
-MESSAGE_LEVEL
--------------
-
-Default: ``messages.INFO``
-
-This sets the minimum message that will be saved in the message storage. See
-`Message levels`_ above for more details.
-
-.. admonition:: Important
-
-   If you override ``MESSAGE_LEVEL`` in your settings file and rely on any of
-   the built-in constants, you must import the constants module directly to
-   avoid the potential for circular imports, e.g.::
-
-       from django.contrib.messages import constants as message_constants
-       MESSAGE_LEVEL = message_constants.DEBUG
-
-   If desired, you may specify the numeric values for the constants directly
-   according to the values in the above :ref:`constants table
-   <message-level-constants>`.
-
-MESSAGE_STORAGE
----------------
-
-Default: ``'django.contrib.messages.storage.fallback.FallbackStorage'``
-
-Controls where Django stores message data. Valid values are:
-
-* ``'django.contrib.messages.storage.fallback.FallbackStorage'``
-* ``'django.contrib.messages.storage.session.SessionStorage'``
-* ``'django.contrib.messages.storage.cookie.CookieStorage'``
-
-See `Storage backends`_ for more details.
-
-MESSAGE_TAGS
-------------
-
-Default::
-
-        {messages.DEBUG: 'debug',
-        messages.INFO: 'info',
-        messages.SUCCESS: 'success',
-        messages.WARNING: 'warning',
-        messages.ERROR: 'error',}
-
-This sets the mapping of message level to message tag, which is typically
-rendered as a CSS class in HTML. If you specify a value, it will extend
-the default. This means you only have to specify those values which you need
-to override. See `Displaying messages`_ above for more details.
-
-.. admonition:: Important
-
-   If you override ``MESSAGE_TAGS`` in your settings file and rely on any of
-   the built-in constants, you must import the ``constants`` module directly to
-   avoid the potential for circular imports, e.g.::
-
-       from django.contrib.messages import constants as message_constants
-       MESSAGE_TAGS = {message_constants.INFO: ''}
-
-   If desired, you may specify the numeric values for the constants directly
-   according to the values in the above :ref:`constants table
-   <message-level-constants>`.
-
-SESSION_COOKIE_DOMAIN
----------------------
-
-Default: ``None``
-
-The storage backends that use cookies -- ``CookieStorage`` and
-``FallbackStorage`` -- use the value of :setting:`SESSION_COOKIE_DOMAIN` in
-setting their cookies. See the :doc:`settings documentation </ref/settings>`
-for more information on how this works and why you might need to set it.
-
-.. _Django settings: ../settings/
+* :setting:`MESSAGE_LEVEL`
+* :setting:`MESSAGE_STORAGE`
+* :setting:`MESSAGE_TAGS`
+* :ref:`SESSION_COOKIE_DOMAIN<messages-session_cookie_domain>`
diff --git a/docs/ref/contrib/staticfiles.txt b/docs/ref/contrib/staticfiles.txt
index a4a60f239b..a7540388bc 100644
--- a/docs/ref/contrib/staticfiles.txt
+++ b/docs/ref/contrib/staticfiles.txt
@@ -19,106 +19,14 @@ can easily be served in production.
 Settings
 ========
 
-.. highlight:: python
-
-.. note::
-
-    The following settings control the behavior of the staticfiles app.
-
-.. setting:: STATICFILES_DIRS
-
-STATICFILES_DIRS
-----------------
-
-Default: ``[]``
-
-This setting defines the additional locations the staticfiles app will traverse
-if the ``FileSystemFinder`` finder is enabled, e.g. if you use the
-:djadmin:`collectstatic` or :djadmin:`findstatic` management command or use the
-static file serving view.
-
-This should be set to a list or tuple of strings that contain full paths to
-your additional files directory(ies) e.g.::
-
-    STATICFILES_DIRS = (
-        "/home/special.polls.com/polls/static",
-        "/home/polls.com/polls/static",
-        "/opt/webfiles/common",
-    )
-
-Prefixes (optional)
-"""""""""""""""""""
-
-In case you want to refer to files in one of the locations with an additional
-namespace, you can **optionally** provide a prefix as ``(prefix, path)``
-tuples, e.g.::
-
-    STATICFILES_DIRS = (
-        # ...
-        ("downloads", "/opt/webfiles/stats"),
-    )
-
-Example:
-
-Assuming you have :setting:`STATIC_URL` set ``'/static/'``, the
-:djadmin:`collectstatic` management command would collect the "stats" files
-in a ``'downloads'`` subdirectory of :setting:`STATIC_ROOT`.
-
-This would allow you to refer to the local file
-``'/opt/webfiles/stats/polls_20101022.tar.gz'`` with
-``'/static/downloads/polls_20101022.tar.gz'`` in your templates, e.g.:
-
-.. code-block:: html+django
-
-    <a href="{{ STATIC_URL }}downloads/polls_20101022.tar.gz">
-
-.. setting:: STATICFILES_STORAGE
-
-STATICFILES_STORAGE
--------------------
-
-Default: ``'django.contrib.staticfiles.storage.StaticFilesStorage'``
-
-The file storage engine to use when collecting static files with the
-:djadmin:`collectstatic` management command.
-
-A ready-to-use instance of the storage backend defined in this setting
-can be found at ``django.contrib.staticfiles.storage.staticfiles_storage``.
-
-For an example, see :ref:`staticfiles-from-cdn`.
-
-.. setting:: STATICFILES_FINDERS
-
-STATICFILES_FINDERS
--------------------
-
-Default::
-
-    ("django.contrib.staticfiles.finders.FileSystemFinder",
-     "django.contrib.staticfiles.finders.AppDirectoriesFinder")
-
-The list of finder backends that know how to find static files in
-various locations.
-
-The default will find files stored in the :setting:`STATICFILES_DIRS` setting
-(using ``django.contrib.staticfiles.finders.FileSystemFinder``) and in a
-``static`` subdirectory of each app (using
-``django.contrib.staticfiles.finders.AppDirectoriesFinder``)
-
-One finder is disabled by default:
-``django.contrib.staticfiles.finders.DefaultStorageFinder``. If added to
-your :setting:`STATICFILES_FINDERS` setting, it will look for static files in
-the default file storage as defined by the :setting:`DEFAULT_FILE_STORAGE`
-setting.
-
-.. note::
-
-    When using the ``AppDirectoriesFinder`` finder, make sure your apps
-    can be found by staticfiles. Simply add the app to the
-    :setting:`INSTALLED_APPS` setting of your site.
+See :ref:`staticfiles settings <settings-staticfiles>` for details on the
+following settings:
 
-Static file finders are currently considered a private interface, and this
-interface is thus undocumented.
+* :setting:`STATIC_ROOT`
+* :setting:`STATIC_URL`
+* :setting:`STATICFILES_DIRS`
+* :setting:`STATICFILES_STORAGE`
+* :setting:`STATICFILES_FINDERS`
 
 Management Commands
 ===================