diff --git a/doc/configuration.rst b/doc/configuration.rst index a94a4d69dc1..4cc8253f6f1 100644 --- a/doc/configuration.rst +++ b/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,8 +831,10 @@ Default value: (none) This controls if new datasets will require moderation approval before going public. +.. _ckan-tracking-enabled: + ckan.tracking_enabled ---------------------- +^^^^^^^^^^^^^^^^^^^^^ Example:: @@ -839,11 +842,82 @@ Example:: 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,6 +930,10 @@ Default value: ``None`` This controls from which email the error messages will come from. + +Authorization Settings +---------------------- + debug ^^^^^ @@ -863,7 +941,7 @@ 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. diff --git a/doc/email-notifications.rst b/doc/email-notifications.rst index 90b8beb4c35..5b0f6ce7661 100644 --- a/doc/email-notifications.rst +++ b/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 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!):: diff --git a/doc/tracking.rst b/doc/tracking.rst index 384028e8a76..d7ce42e94f7 100644 --- a/doc/tracking.rst +++ b/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]