[#534] Add E-mail Settings section and add cross-references to the co…

…nfig options.

doc/configuration.rst

@@ -29,6 +29,8 @@ This defines the database that CKAN is to use. The format is::
 Front-End Settings
 ------------------
 
+.. _ckan-site-title:
+
 ckan.site_title
 ^^^^^^^^^^^^^^^
 
@@ -235,7 +237,7 @@ Example::
 
 Default value: ``(none)``
 
-This controls the feed author's name. If unspecified, it'll use ckan.site_id.
+This controls the feed author's name. If unspecified, it'll use :ref:`ckan-site-id`.
 
 ckan.feeds.author_link
 ^^^^^^^^^^^^^^^^^^^^^^
@@ -246,7 +248,7 @@ Example::
 
 Default value: ``(none)``
 
-This controls the feed author's link. If unspecified, it'll use ckan.site_url.
+This controls the feed author's link. If unspecified, it'll use :ref:`ckan-site-url`.
 
 ckan.feeds.authority_name
 ^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -257,7 +259,7 @@ Example::
 
 Default value: ``(none)``
 
-The domain name or email address of the default publisher of the feeds and elements. If unspecified, it'll use ckan.site_url.
+The domain name or email address of the default publisher of the feeds and elements. If unspecified, it'll use :ref:`ckan-site-url`.
 
 ckan.feeds.date
 ^^^^^^^^^^^^^^^
@@ -324,6 +326,8 @@ Default value:  ``True``
 
 Turns on and off the activity streams used to track changes on datasets, groups, users, etc
 
+.. _ckan-activity-streams-email-notifications:
+
 ckan.activity_streams_email_notifications
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -648,6 +652,8 @@ These are the setup parameters for AMQP messaging. These only apply if the messa
 Search Settings
 ---------------
 
+.. _ckan-site-id:
+
 ckan.site_id
 ^^^^^^^^^^^^
 
@@ -751,17 +757,23 @@ List of the extra resource fields that would be used when searching.
 Site Settings
 -------------
 
+.. _ckan-site-url:
+
 ckan.site_url
 ^^^^^^^^^^^^^
 
 Example::
 
- ckan.site_url = http://scotdata.ckan.net
+  ckan.site_url = http://scotdata.ckan.net
 
 Default value:  (none)
 
 The primary URL used by this site. Used in the API to provide datasets with links to themselves in the web UI.
 
+.. warning::
+
+  This setting should not have a trailing / on the end.
+
 ckan.api_url
 ^^^^^^^^^^^^
 
@@ -786,17 +798,6 @@ Default value: ``X-CKAN-API-Key`` & ``Authorization``
 
 This allows another http header to be used to provide the CKAN API key. This is useful if network infrastructure block the Authorization header and ``X-CKAN-API-Key`` is not suitable.
 
-email_to
-^^^^^^^^
-
-Example::
-
-  email_to = you@yourdomain.com
-
-Default value: ``None``
-
-This controls where the error messages will be sent to.
-
 ckan.cache_expires
 ^^^^^^^^^^^^^^^^^^
 
@@ -830,20 +831,93 @@ Default value: (none)
 
 This controls if new datasets will require moderation approval before going public.
 
+.. _ckan-tracking-enabled:
+
 ckan.tracking_enabled
----------------------
+^^^^^^^^^^^^^^^^^^^^^
 
 Example::
 
   ckan.tracking_enabled = True
 
 Default value: ``False``
 
-This controls if CKAN will track the site usage.
+This controls if CKAN will track the site usage. For more info, read :ref:`tracking`.
 
 
-Authorization Settings
-----------------------
+.. _email-settings:
+
+E-mail Settings
+---------------
+
+smtp.server
+^^^^^^^^^^^
+
+Example::
+
+  smtp.server = smtp.gmail.com:587
+
+Default value: ``None``
+
+The SMTP server to connect to when sending emails with optional port.
+
+smtp.starttls
+^^^^^^^^^^^^^
+
+Example::
+
+  smtp.starttls = True
+
+Default value: ``None``
+
+Whether or not to use STARTTLS when connecting to the SMTP server.
+
+smtp.user
+^^^^^^^^^
+
+Example::
+
+  smtp.user = your_username@gmail.com
+
+Default value: ``None``
+
+The username used to authenticate with the SMTP server.
+
+smtp.password
+^^^^^^^^^^^^^
+
+Example::
+
+  smtp.password = yourpass
+
+Default value: ``None``
+
+The password used to authenticate with the SMTP server.
+
+.. _smtp-mail-from:
+
+smtp.mail_from
+^^^^^^^^^^^^^^
+
+Example::
+
+  smtp.mail_from = you@yourdomain.com
+
+Default value: ``None``
+
+The email address that emails sent by CKAN will come from. Note that, if left blank, the
+SMTP server may insert its own.
+
+email_to
+^^^^^^^^
+
+Example::
+
+  email_to = you@yourdomain.com
+
+Default value: ``None``
+
+This controls where the error messages will be sent to.
 
 error_email_from
 ^^^^^^^^^^^^^^^^
@@ -856,14 +930,18 @@ Default value: ``None``
 
 This controls from which email the error messages will come from.
 
+
+Authorization Settings
+----------------------
+
 debug
 ^^^^^
 
 Example::
 
   debug = False
 
-Default value: False
+Default value: ``False``
 
 This enables Pylons' interactive debugging tool, makes Fanstatic serve unminified JS and CSS
 files, and enables CKAN templates' debugging features.
@@ -879,7 +957,7 @@ Example::
 
   ckan.debug_supress_header = False
 
-Default value: False
+Default value: ``False``
 
 This configs if the debug information showing the controller and action
 receiving the request being is shown in the header.

doc/email-notifications.rst

@@ -43,37 +43,33 @@ notifications for a CKAN site, a sysadmin must:
 
 2. CKAN will not send out any email notifications, nor show the email
    notifications preference to users, unless the
-   ``ckan.activity_streams_email_notifications`` option is set to ``True``, so
+   :ref:`ckan-activity-streams-email-notifications` option is set to ``True``, so
    put this line in the ``[app:main]`` section of your CKAN config file::
 
     ckan.activity_streams_email_notifications = True
 
 
-3. Make sure that ``ckan.site_url`` is set correctly in the ``[app:main]``
+3. Make sure that :ref:`ckan-site-url` is set correctly in the ``[app:main]``
    section of your CKAN configuration file. This is used to generate links in
    the bodies of the notification emails. For example::
 
     ckan.site_url = http://publicdata.eu
 
-   .. warning::
-
-    The ``ckan.site_url`` setting should not have a trailing ``/`` on the end!
-
 
-4. Make sure that ``smtp.mail_from`` is set correctly in the ``[app:main]``
+4. Make sure that :ref:`smtp-mail-from` is set correctly in the ``[app:main]``
    section of your CKAN configuration file. This is the email address that
    CKAN's email notifications will appear to come from. For example::
 
     smtp.mail_from = mailman@publicdata.eu
 
-   This is combined with your ``ckan.site_title`` to form the ``From:`` header
+   This is combined with your :ref:`ckan-site-title` to form the ``From:`` header
    of the email that are sent, for example::
 
     From: PublicData.eu <mailmain@publicdata.eu>
 
 
 5. If you do not have an SMTP server running locally on the machine that hosts
-   your CKAN instance, you can use CKAN's SMTP settings to send email via an
+   your CKAN instance, you can change the :ref:`email-settings` to send email via an
    external SMTP server. For example, these settings in the ``[app:main]``
    section of your configuration file will send emails using a gmail account
    (not recommended for production websites!)::

doc/tracking.rst

@@ -1,3 +1,5 @@
+.. _tracking:
+
 ==================
 Page View Tracking
 ==================
@@ -21,7 +23,7 @@ Enabling Page View Tracking
 
 To enable page view tracking:
 
-1. Put ``ckan.tracking_enabled = true`` in the ``[app:main]`` section of your
+1. Set :ref:`ckan-tracking-enabled` to true in the ``[app:main]`` section of your
    CKAN configuration file (e.g. ``development.ini`` or ``production.ini``)::
 
     [app:main]