From f8c122723f8de4d986c0b88a2a563f9570212360 Mon Sep 17 00:00:00 2001
From: Vitor Baptista
Date: Fri, 22 Mar 2013 15:45:50 -0300
Subject: [PATCH 1/8] [#534] Update configuration flags' documentation
---
doc/configuration.rst | 308 ++++++++++++++++++++++++++++++++++--------
1 file changed, 252 insertions(+), 56 deletions(-)
diff --git a/doc/configuration.rst b/doc/configuration.rst
index 6e9bae57393..167dee759cd 100644
--- a/doc/configuration.rst
+++ b/doc/configuration.rst
@@ -35,15 +35,112 @@ Front-End Settings
------------------
+.. index::
+ single: ckan.feeds.author_name
+
+ckan.feeds.author_name
+^^^^^^^^^^^^^^^^^^^^^^
+
+Example::
+
+ ckan.feeds.author_name = Michael Jackson
+
+Default value: ``(none)``
+
+This controls the feed author's name. If unspecified, it'll use ckan.site_id.
+
+.. index::
+ single: ckan.feeds.author_link
+
+ckan.feeds.author_link
+^^^^^^^^^^^^^^^^^^^^^^
+
+Example::
+
+ ckan.feeds.author_link = http://okfn.org
+
+Default value: ``(none)``
+
+This controls the feed author's link. If unspecified, it'll use ckan.site_url.
+
+.. index::
+ single: ckan.feeds.authority_name
+
+ckan.feeds.authority_name
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Example::
+
+ ckan.feeds.authority_name = http://okfn.org
+
+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.
+
+.. index::
+ single: ckan.feeds.date
+
+ckan.feeds.date
+^^^^^^^^^^^^^^^
+
+Example::
+
+ ckan.feeds.date = 2012-03-22
+
+Default value: ``(none)``
+
+A string representing the default date on which the authority_name is owned by the publisher of the feed.
+
.. index::
single: site_description
+.. index::
+ ckan.gravatar_default
+
+ckan.gravatar_default
+^^^^^^^^^^^^^^^^^^^^^
+
+Example::
+
+ ckan.gravatar_default = monsterid
+
+Default value: ``identicon``
+
+This controls the default gravatar avatar, in case the user has none.
+
+ckan.legacy_templates
+^^^^^^^^^^^^^^^^^^^^^
+
+Example::
+
+ ckan.legacy_templates = True
+
+Default value: ``False``
+
+This controls if the legacy genshi templates are used.
+
+.. note:: This is only for legacy code, and shouldn't be used anymore.
+
+.. index::
+ single: site_title
+
+site_title
+^^^^^^^^^^
+
+Example::
+
+ ckan.site_title=Open Data Scotland
+
+Default value: ``CKAN``
+
+This sets the name of the site, as displayed in the CKAN web interface.
+
site_description
^^^^^^^^^^^^^^^^
Example::
- ckan.site_description=
+ ckan.site_description = The easy way to get, use and share data
Default value: (none)
@@ -63,12 +160,6 @@ Default value: (none)
This sets the logo used in the title bar.
-.. index::
- single: site_url
-
-
-.. index::
- single: package_hide_extras
favicon
^^^^^^^
@@ -86,25 +177,41 @@ site_about
Example::
- ckan.site_about=${g.site_title} is a community-driven catalogue of open data for the Greenfield area.
+ ckan.site_about=A _community-driven_ catalogue of _open data_ for the Greenfield area.
Default value::
- What was the average price of a house in the UK in 1935? When will India's projected population overtake that of China? Where can you see publicly-funded art in Seattle? Data to answer many, many questions like these is out there on the Internet somewhere - but it is not always easy to find.
+
CKAN is the world’s leading open-source data portal platform.
+
+
CKAN is a complete out-of-the-box software solution that makes data
+ accessible and usable – by providing tools to streamline publishing, sharing,
+ finding and using data (including storage of data and provision of robust data
+ APIs). CKAN is aimed at data publishers (national and regional governments,
+ companies and organizations) wanting to make their data open and available.
-
${g.site_title} is a community-run catalogue of useful sets of data on the Internet. You can collect links here to data from around the web for yourself and others to use, or search for data that others have collected. Depending on the type of data (and its conditions of use), ${g.site_title} may also be able to store a copy of the data or host it in a database, and provide some basic visualisation tools.
+
CKAN is used by governments and user groups worldwide and powers a variety
+ of official and community data portals including portals for local, national
+ and international government, such as the UK’s data.gov.uk
+ and the European Union’s publicdata.eu,
+ the Brazilian dados.gov.br, Dutch and
+ Netherland government portals, as well as city and municipal sites in the US,
+ UK, Argentina, Finland and elsewhere.
-This changes the text about the site on the 'About' page. i.e. replaces the text in the "About CKAN: http://ckan.org/
+ CKAN Tour: http://ckan.org/tour/
+ Features overview: http://ckan.org/features/
Format tips:
* multiline strings can be used by indenting following lines
- * the format is basically HTML, but with Genshi-format strings
-
- * the about text will be automatically be placed with-in paragraph tags ``
...
`` but you can start new paragraphs within that by using ``
``
+ * the format is Markdown
.. note:: Whilst the default text is translated into many languages (switchable in the page footer), the text in this configuration option will not be translatable.
+ For this reason, it's better to overload the snippet in ``home/snippets/about_text.html``. For more information, see :doc:`theming`.
+
+.. index::
+ single: package_hide_extras
package_hide_extras
^^^^^^^^^^^^^^^^^^^
@@ -192,6 +299,19 @@ Default value: ``20``
This controls the pagination of the dataset search results page. This is the maximum number of datasets viewed per page of results.
+
+ckan.activity_list_limit
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Example::
+
+ ckan.activity_list_limit = 31
+
+Default value: ``infinite``
+
+This controls the number of activities to show in the Activity Stream. By default, it shows everything.
+
+
ckan.preview.direct
^^^^^^^^^^^^^^^^^^^
@@ -214,25 +334,6 @@ Default value: ``html htm rdf+xml owl+xml xml n3 n-triples turtle plain atom rss
Defines the resource formats which should be loaded directly in an `iframe`
tag when previewing them.
-Authentication Settings
------------------------
-
-.. index::
- single: openid_enabled
-
-openid_enabled
-^^^^^^^^^^^^^^
-
-Example::
-
- openid_enabled = False
-
-Default value: ``True``
-
-CKAN operates a delegated authentication model based on `OpenID `_.
-
-Setting this option to False turns off OpenID for login.
-
Activity Streams Settings
-----------------------
@@ -310,7 +411,21 @@ Storage Settings
----------------
.. index::
- single: ckan.storage.bucket, ofs.storage_dir
+ single: ckan.cache_enabled
+
+ckan.cache_enabled
+^^^^^^^^^^^^^^^^^^
+
+Example::
+
+ ckan.cache_enabled = True
+
+Default value: ``None``
+
+Controls if we're caching CKAN's static files, if it's serving them.
+
+.. index::
+ single: ckan.storage.bucket
ckan.storage.bucket
^^^^^^^^^^^^^^^^^^^
@@ -353,6 +468,8 @@ To customise the display of CKAN you can supply replacements for the Genshi temp
For more information on theming, see :doc:`theming`.
+.. note:: This is only for legacy code, and shouldn't be used anymore.
+
.. index::
single: extra_public_paths
@@ -367,6 +484,8 @@ To customise the display of CKAN you can supply replacements for static files su
For more information on theming, see :doc:`theming`.
+.. note:: This is only for legacy code, and shouldn't be used anymore.
+
template_head_end
^^^^^^^^^^^^^^^^^
@@ -382,6 +501,8 @@ You can also have multiline strings. Just indent following lines. e.g.::
+.. note:: This is only for legacy code, and shouldn't be used anymore.
+
template_footer_end
^^^^^^^^^^^^^^^^^^^
@@ -402,6 +523,8 @@ Example (showing insertion of Google Analytics code)::
+.. note:: This is only for legacy code, and shouldn't be used anymore.
+
Form Settings
-------------
@@ -511,6 +634,18 @@ These are the setup parameters for AMQP messaging. These only apply if the messa
Search Settings
---------------
+.. index::
+ single: ckan.extra_resource_fields
+
+Example::
+
+ ckan.extra_resource_fields = alt_url
+
+Default value: ``None``
+
+List of the extra resource fields that would be used when searching.
+
+
.. index::
single: ckan.site_id
@@ -603,18 +738,68 @@ Site Settings
-------------
.. index::
- single: site_title
+ single: ckan.debug_supress_header
-site_title
-^^^^^^^^^^
+ckan.debug_supress_header
+^^^^^^^^^^^^^^^^^^^^^^^^^
Example::
- ckan.site_title=Open Data Scotland
+ ckan.debug_supress_header = False
-Default value: ``CKAN``
+Default value: False
-This sets the name of the site, as displayed in the CKAN web interface.
+This configs if the debug information showing the controller and action
+receiving the request being is shown in the header.
+
+.. note:: This info only shows if debug is set to True.
+
+.. index::
+ single: debug
+
+debug
+^^^^^
+
+Example::
+
+ debug = False
+
+Default value: False
+
+This enables Pylons' interactive debugging tool, makes Fanstatic serve unminified JS and CSS
+files, and enables CKAN templates' debugging features.
+
+.. warning:: THIS SETTING MUST BE SET TO FALSE ON A PRODUCTION ENVIRONMENT.
+ Debug mode will enable the interactive debugging tool, allowing ANYONE to
+ execute malicious code after an exception is raised.
+
+.. index::
+ single: email_to
+
+email_to
+^^^^^^^^
+
+Example::
+
+ email_to = you@yourdomain.com
+
+Default value: ``None``
+
+This controls where the error messages will be sent to.
+
+.. index::
+ single: error_email_from
+
+error_email_from
+^^^^^^^^^^^^^^^^
+
+Example::
+
+ error_email_from = paste@localhost
+
+Default value: ``None``
+
+This controls from which email the error messages will come from.
.. index::
single: site_url
@@ -657,30 +842,23 @@ 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.
-Authorization Settings
-----------------------
-
-.. index::
- single: default_roles, auth_profile
-default_roles
-^^^^^^^^^^^^^
+Plugin Settings
+---------------
-This allows you to set the default authorization roles (i.e. permissions) for new objects. Currently this extends to new datasets, groups, authorization groups and the ``system`` object. For full details of these, see :doc:`authorization`.
+.. index::
+ single: ckanext.stats.cache_enabled
-The value is a strict JSON dictionary of user names ``visitor`` (any user who is not logged in) and ``logged_in`` (any user who is logged in) with lists of their roles.
+ckanext.stats.cache_enabled
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
Example::
- ckan.default_roles.Package = {"visitor": ["editor"], "logged_in": ["editor"]}
- ckan.default_roles.Group = {"visitor": ["reader"], "logged_in": ["reader"]}
-
-With this example setting, visitors and logged-in users can only read datasets that get created.
+ ckanext.stats.cache_enabled = True
-Defaults: see in ``ckan/model/authz.py`` for: ``default_default_user_roles``
+Default value: ``True``
-Plugin Settings
----------------
+This controls if we'll use the 1 day cache for stats.
.. index::
single: plugins
@@ -698,6 +876,24 @@ Specify which CKAN extensions are to be enabled.
Format as a space-separated list of the extension names. The extension name is the key in the [ckan.plugins] section of the extension's ``setup.py``. For more information on extensions, see :doc:`extensions`.
+.. index::
+ single: ckan.datastore.enabled
+
+ckan.datastore.enabled
+^^^^^^^^^^^^^^^^^^^^^^
+
+Example::
+
+ ckan.datastore.enabled = True
+
+Default value: ``False``
+
+Controls if the Data API link will appear in Dataset's Resource page.
+
+.. note:: This setting only applies to the legacy templates.
+
+.. index::
+ single: ckan.storage.bucket, ofs.storage_dir
Directory Settings
From 5621e48c89a22983fbae95651254cbbb9fba550e Mon Sep 17 00:00:00 2001
From: Vitor Baptista
Date: Wed, 27 Mar 2013 16:27:49 -0300
Subject: [PATCH 2/8] [#534] Reorganize configuration flags' order in the docs
---
doc/configuration.rst | 478 +++++++++++++++++++++---------------------
1 file changed, 238 insertions(+), 240 deletions(-)
diff --git a/doc/configuration.rst b/doc/configuration.rst
index 167dee759cd..5b2598cb92d 100644
--- a/doc/configuration.rst
+++ b/doc/configuration.rst
@@ -35,92 +35,6 @@ Front-End Settings
------------------
-.. index::
- single: ckan.feeds.author_name
-
-ckan.feeds.author_name
-^^^^^^^^^^^^^^^^^^^^^^
-
-Example::
-
- ckan.feeds.author_name = Michael Jackson
-
-Default value: ``(none)``
-
-This controls the feed author's name. If unspecified, it'll use ckan.site_id.
-
-.. index::
- single: ckan.feeds.author_link
-
-ckan.feeds.author_link
-^^^^^^^^^^^^^^^^^^^^^^
-
-Example::
-
- ckan.feeds.author_link = http://okfn.org
-
-Default value: ``(none)``
-
-This controls the feed author's link. If unspecified, it'll use ckan.site_url.
-
-.. index::
- single: ckan.feeds.authority_name
-
-ckan.feeds.authority_name
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Example::
-
- ckan.feeds.authority_name = http://okfn.org
-
-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.
-
-.. index::
- single: ckan.feeds.date
-
-ckan.feeds.date
-^^^^^^^^^^^^^^^
-
-Example::
-
- ckan.feeds.date = 2012-03-22
-
-Default value: ``(none)``
-
-A string representing the default date on which the authority_name is owned by the publisher of the feed.
-
-.. index::
- single: site_description
-
-.. index::
- ckan.gravatar_default
-
-ckan.gravatar_default
-^^^^^^^^^^^^^^^^^^^^^
-
-Example::
-
- ckan.gravatar_default = monsterid
-
-Default value: ``identicon``
-
-This controls the default gravatar avatar, in case the user has none.
-
-ckan.legacy_templates
-^^^^^^^^^^^^^^^^^^^^^
-
-Example::
-
- ckan.legacy_templates = True
-
-Default value: ``False``
-
-This controls if the legacy genshi templates are used.
-
-.. note:: This is only for legacy code, and shouldn't be used anymore.
-
.. index::
single: site_title
@@ -160,18 +74,6 @@ Default value: (none)
This sets the logo used in the title bar.
-
-favicon
-^^^^^^^
-
-Example::
-
- ckan.favicon = http://okfn.org/wp-content/themes/okfn-master-wordpress-theme/images/favicon.ico
-
-Default value: ``/images/icons/ckan.ico``
-
-This sets the site's `favicon`. This icon is usually displayed by the browser in the tab heading and bookmark.
-
site_about
^^^^^^^^^^
@@ -210,8 +112,31 @@ Format tips:
.. note:: Whilst the default text is translated into many languages (switchable in the page footer), the text in this configuration option will not be translatable.
For this reason, it's better to overload the snippet in ``home/snippets/about_text.html``. For more information, see :doc:`theming`.
+favicon
+^^^^^^^
+
+Example::
+
+ ckan.favicon = http://okfn.org/wp-content/themes/okfn-master-wordpress-theme/images/favicon.ico
+
+Default value: ``/images/icons/ckan.ico``
+
+This sets the site's `favicon`. This icon is usually displayed by the browser in the tab heading and bookmark.
+
.. index::
- single: package_hide_extras
+ single: ckan.feeds.author_name
+
+datasets_per_page
+^^^^^^^^^^^^^^^^^
+
+Example::
+
+ ckan.datasets_per_page = 10
+
+Default value: ``20``
+
+This controls the pagination of the dataset search results page. This is the maximum number of datasets viewed per page of results.
+
package_hide_extras
^^^^^^^^^^^^^^^^^^^
@@ -226,9 +151,6 @@ This sets a space-separated list of extra field key values which will not be sho
.. warning:: While this is useful to e.g. create internal notes, it is not a security measure. The keys will still be available via the API and in revision diffs.
-.. index::
- single: rdf_packages
-
.. _config-apps-ideas:
ckan.dataset.show_apps_ideas
@@ -242,6 +164,43 @@ Default value: true
When set to false, or no, this setting will hide the 'Apps, Ideas, etc' tab on the package read page. If the value is not set, or is set to true or yes, then the tab will shown.
+.. index::
+ single: rdf_packages
+
+ckan.activity_list_limit
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Example::
+
+ ckan.activity_list_limit = 31
+
+Default value: ``infinite``
+
+This controls the number of activities to show in the Activity Stream. By default, it shows everything.
+
+
+ckan.preview.direct
+^^^^^^^^^^^^^^^^^^^
+
+Example::
+ ckan.preview.direct = png jpg gif
+
+Default value: ``png jpg gif``
+
+Defines the resource formats which should be embedded directly in an `img` tag
+when previewing them.
+
+ckan.preview.loadable
+^^^^^^^^^^^^^^^^^^^^^
+
+Example::
+ ckan.preview.loadable = html htm rdf+xml owl+xml xml n3 n-triples turtle plain atom rss txt
+
+Default value: ``html htm rdf+xml owl+xml xml n3 n-triples turtle plain atom rss txt``
+
+Defines the resource formats which should be loaded directly in an `iframe`
+tag when previewing them.
+
rdf_packages
^^^^^^^^^^^^
@@ -288,51 +247,91 @@ And there is an option for the default expiry time if not specified::
ckan.cache.default_expires = 600
-datasets_per_page
-^^^^^^^^^^^^^^^^^
+ckan.feeds.author_name
+^^^^^^^^^^^^^^^^^^^^^^
Example::
- ckan.datasets_per_page = 10
+ ckan.feeds.author_name = Michael Jackson
-Default value: ``20``
+Default value: ``(none)``
-This controls the pagination of the dataset search results page. This is the maximum number of datasets viewed per page of results.
+This controls the feed author's name. If unspecified, it'll use ckan.site_id.
+.. index::
+ single: ckan.feeds.author_link
-ckan.activity_list_limit
-^^^^^^^^^^^^^^^^^^^^^^^^
+ckan.feeds.author_link
+^^^^^^^^^^^^^^^^^^^^^^
Example::
- ckan.activity_list_limit = 31
+ ckan.feeds.author_link = http://okfn.org
-Default value: ``infinite``
+Default value: ``(none)``
-This controls the number of activities to show in the Activity Stream. By default, it shows everything.
+This controls the feed author's link. If unspecified, it'll use ckan.site_url.
+.. index::
+ single: ckan.feeds.authority_name
-ckan.preview.direct
-^^^^^^^^^^^^^^^^^^^
+ckan.feeds.authority_name
+^^^^^^^^^^^^^^^^^^^^^^^^^
Example::
- ckan.preview.direct = png jpg gif
-Default value: ``png jpg gif``
+ ckan.feeds.authority_name = http://okfn.org
-Defines the resource formats which should be embedded directly in an `img` tag
-when previewing them.
+Default value: ``(none)``
-ckan.preview.loadable
+The domain name or email address of the default publisher of the feeds and elements. If unspecified, it'll use ckan.site_url.
+
+.. index::
+ single: ckan.feeds.date
+
+ckan.feeds.date
+^^^^^^^^^^^^^^^
+
+Example::
+
+ ckan.feeds.date = 2012-03-22
+
+Default value: ``(none)``
+
+A string representing the default date on which the authority_name is owned by the publisher of the feed.
+
+.. index::
+ single: site_description
+
+.. index::
+ ckan.gravatar_default
+
+ckan.gravatar_default
^^^^^^^^^^^^^^^^^^^^^
Example::
- ckan.preview.loadable = html htm rdf+xml owl+xml xml n3 n-triples turtle plain atom rss txt
-Default value: ``html htm rdf+xml owl+xml xml n3 n-triples turtle plain atom rss txt``
+ ckan.gravatar_default = monsterid
-Defines the resource formats which should be loaded directly in an `iframe`
-tag when previewing them.
+Default value: ``identicon``
+
+This controls the default gravatar avatar, in case the user has none.
+
+.. index::
+ single: package_hide_extras
+
+ckan.legacy_templates
+^^^^^^^^^^^^^^^^^^^^^
+
+Example::
+
+ ckan.legacy_templates = True
+
+Default value: ``False``
+
+This controls if the legacy genshi templates are used.
+
+.. note:: This is only for legacy code, and shouldn't be used anymore.
Activity Streams Settings
-----------------------
@@ -410,20 +409,6 @@ If you want to specify the ordering of all or some of the locales as they are of
Storage Settings
----------------
-.. index::
- single: ckan.cache_enabled
-
-ckan.cache_enabled
-^^^^^^^^^^^^^^^^^^
-
-Example::
-
- ckan.cache_enabled = True
-
-Default value: ``None``
-
-Controls if we're caching CKAN's static files, if it's serving them.
-
.. index::
single: ckan.storage.bucket
@@ -438,6 +423,9 @@ Default value: ``None``
This setting will change the bucket name for the uploaded files.
+.. index::
+ single: ofs.storage_dir
+
ofs.storage_dir
^^^^^^^^^^^^^^^
@@ -449,42 +437,25 @@ Default value: ``None``
Use this to specify where uploaded files should be stored, and also to turn on the handling of file storage. The folder should exist, and will automatically be turned into a valid pairtree repository if it is not already.
-
-
-Theming Settings
-----------------
-
.. index::
- single: extra_template_paths
+ single: ckan.cache_enabled
-extra_template_paths
-^^^^^^^^^^^^^^^^^^^^
+ckan.cache_enabled
+^^^^^^^^^^^^^^^^^^
Example::
- extra_template_paths=/home/okfn/brazil_ckan_config/templates
+ ckan.cache_enabled = True
-To customise the display of CKAN you can supply replacements for the Genshi template files. Use this option to specify where CKAN should look for additional templates, before reverting to the ``ckan/templates`` folder. You can supply more than one folder, separating the paths with a comma (,).
+Default value: ``None``
-For more information on theming, see :doc:`theming`.
+Controls if we're caching CKAN's static files, if it's serving them.
-.. note:: This is only for legacy code, and shouldn't be used anymore.
+Theming Settings
+----------------
.. index::
- single: extra_public_paths
-
-extra_public_paths
-^^^^^^^^^^^^^^^^^^
-
-Example::
-
- extra_public_paths = /home/okfn/brazil_ckan_config/public
-
-To customise the display of CKAN you can supply replacements for static files such as HTML, CSS, script and PNG files. Use this option to specify where CKAN should look for additional files, before reverting to the ``ckan/public`` folder. You can supply more than one folder, separating the paths with a comma (,).
-
-For more information on theming, see :doc:`theming`.
-
-.. note:: This is only for legacy code, and shouldn't be used anymore.
+ single: extra_template_paths
template_head_end
^^^^^^^^^^^^^^^^^
@@ -525,6 +496,35 @@ Example (showing insertion of Google Analytics code)::
.. note:: This is only for legacy code, and shouldn't be used anymore.
+extra_template_paths
+^^^^^^^^^^^^^^^^^^^^
+
+Example::
+
+ extra_template_paths=/home/okfn/brazil_ckan_config/templates
+
+To customise the display of CKAN you can supply replacements for the Genshi template files. Use this option to specify where CKAN should look for additional templates, before reverting to the ``ckan/templates`` folder. You can supply more than one folder, separating the paths with a comma (,).
+
+For more information on theming, see :doc:`theming`.
+
+.. note:: This is only for legacy code, and shouldn't be used anymore.
+
+.. index::
+ single: extra_public_paths
+
+extra_public_paths
+^^^^^^^^^^^^^^^^^^
+
+Example::
+
+ extra_public_paths = /home/okfn/brazil_ckan_config/public
+
+To customise the display of CKAN you can supply replacements for static files such as HTML, CSS, script and PNG files. Use this option to specify where CKAN should look for additional files, before reverting to the ``ckan/public`` folder. You can supply more than one folder, separating the paths with a comma (,).
+
+For more information on theming, see :doc:`theming`.
+
+.. note:: This is only for legacy code, and shouldn't be used anymore.
+
Form Settings
-------------
@@ -634,18 +634,16 @@ These are the setup parameters for AMQP messaging. These only apply if the messa
Search Settings
---------------
-.. index::
- single: ckan.extra_resource_fields
+simple_search
+^^^^^^^^^^^^^
Example::
- ckan.extra_resource_fields = alt_url
-
-Default value: ``None``
-
-List of the extra resource fields that would be used when searching.
+ ckan.simple_search = true
+Default value: ``false``
+Switching this on tells CKAN search functionality to just query the database, (rather than using Solr). In this setup, search is crude and limited, e.g. no full-text search, no faceting, etc. However, this might be very useful for getting up and running quickly with CKAN.
.. index::
single: ckan.site_id
@@ -672,7 +670,7 @@ solr_url
Example::
- solr_url = http://solr.okfn.org:8983/solr/ckan-schema-1.3
+ solr_url = http://solr.okfn.org:8983/solr/ckan-schema-2.0
Default value: ``http://solr.okfn.org:8983/solr``
@@ -709,69 +707,78 @@ Default value: ``true``
Make ckan commit changes solr after every dataset update change. Turn this to false if on solr 4.0 and you have automatic (soft)commits enabled to improve dataset update/create speed (however there may be a slight delay before dataset gets seen in results).
-ckan.search.show_all_types
+.. index::
+ single: ckan.extra_resource_fields
+
+ckan.extra_resource_fields
^^^^^^^^^^^^^^^^^^^^^^^^^^
Example::
- ckan.search.show_all_types = true
+ ckan.extra_resource_fields = alt_url
-Default value: ``false``
+Default value: ``None``
-Controls whether the default search page (``/dataset``) should show only
-standard datasets or also custom dataset types. Default is to show only
-standard datasets.
+List of the extra resource fields that would be used when searching.
-simple_search
-^^^^^^^^^^^^^
+
+ckan.search.show_all_types
+^^^^^^^^^^^^^^^^^^^^^^^^^^
Example::
- ckan.simple_search = true
+ ckan.search.show_all_types = true
Default value: ``false``
-Switching this on tells CKAN search functionality to just query the database, (rather than using Solr). In this setup, search is crude and limited, e.g. no full-text search, no faceting, etc. However, this might be very useful for getting up and running quickly with CKAN.
+Controls whether the default search page (``/dataset``) should show only
+standard datasets or also custom dataset types. Default is to show only
+standard datasets.
Site Settings
-------------
.. index::
- single: ckan.debug_supress_header
+ single: site_url
-ckan.debug_supress_header
-^^^^^^^^^^^^^^^^^^^^^^^^^
+site_url
+^^^^^^^^
Example::
- ckan.debug_supress_header = False
-
-Default value: False
+ ckan.site_url=http://scotdata.ckan.net
-This configs if the debug information showing the controller and action
-receiving the request being is shown in the header.
+Default value: (none)
-.. note:: This info only shows if debug is set to True.
+The primary URL used by this site. Used in the API to provide datasets with links to themselves in the web UI.
.. index::
- single: debug
+ single: api_url
-debug
-^^^^^
+api_url
+^^^^^^^
Example::
- debug = False
+ ckan.api_url=http://scotdata.ckan.net/api
-Default value: False
+Default value: ``/api``
-This enables Pylons' interactive debugging tool, makes Fanstatic serve unminified JS and CSS
-files, and enables CKAN templates' debugging features.
+The URL that resolves to the CKAN API part of the site. This is useful if the
+API is hosted on a different domain, for example when a third-party site uses
+the forms API.
-.. warning:: THIS SETTING MUST BE SET TO FALSE ON A PRODUCTION ENVIRONMENT.
- Debug mode will enable the interactive debugging tool, allowing ANYONE to
- execute malicious code after an exception is raised.
+apikey_header_name
+^^^^^^^^^^^^^^^^^^
+
+Example::
+
+ apikey_header_name = API-KEY
+
+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.
.. index::
single: email_to
@@ -802,64 +809,44 @@ Default value: ``None``
This controls from which email the error messages will come from.
.. index::
- single: site_url
+ single: debug
-site_url
-^^^^^^^^
+debug
+^^^^^
Example::
- 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.
-
-.. index::
- single: api_url
-
-api_url
-^^^^^^^
+ debug = False
-Example::
+Default value: False
- ckan.api_url=http://scotdata.ckan.net/api
+This enables Pylons' interactive debugging tool, makes Fanstatic serve unminified JS and CSS
+files, and enables CKAN templates' debugging features.
-Default value: ``/api``
+.. warning:: THIS SETTING MUST BE SET TO FALSE ON A PRODUCTION ENVIRONMENT.
+ Debug mode will enable the interactive debugging tool, allowing ANYONE to
+ execute malicious code after an exception is raised.
-The URL that resolves to the CKAN API part of the site. This is useful if the
-API is hosted on a different domain, for example when a third-party site uses
-the forms API.
+.. index::
+ single: ckan.debug_supress_header
-apikey_header_name
-^^^^^^^^^^^^^^^^^^
+ckan.debug_supress_header
+^^^^^^^^^^^^^^^^^^^^^^^^^
Example::
- apikey_header_name = API-KEY
+ ckan.debug_supress_header = False
-Default value: ``X-CKAN-API-Key`` & ``Authorization``
+Default value: False
-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.
+This configs if the debug information showing the controller and action
+receiving the request being is shown in the header.
+.. note:: This info only shows if debug is set to True.
Plugin Settings
---------------
-.. index::
- single: ckanext.stats.cache_enabled
-
-ckanext.stats.cache_enabled
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Example::
-
- ckanext.stats.cache_enabled = True
-
-Default value: ``True``
-
-This controls if we'll use the 1 day cache for stats.
-
.. index::
single: plugins
@@ -893,7 +880,18 @@ Controls if the Data API link will appear in Dataset's Resource page.
.. note:: This setting only applies to the legacy templates.
.. index::
- single: ckan.storage.bucket, ofs.storage_dir
+ single: ckanext.stats.cache_enabled
+
+ckanext.stats.cache_enabled
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Example::
+
+ ckanext.stats.cache_enabled = True
+
+Default value: ``True``
+
+This controls if we'll use the 1 day cache for stats.
Directory Settings
From 3c5130e45b690625c9a317d33c74fb2482529a8c Mon Sep 17 00:00:00 2001
From: Vitor Baptista
Date: Mon, 22 Apr 2013 11:23:30 -0300
Subject: [PATCH 3/8] [#534] Add documentation for some configuration flags
---
doc/configuration.rst | 290 ++++++++++++++++++++++++++++--------
doc/email-notifications.rst | 2 +
doc/filestore.rst | 6 +-
doc/solr-setup.rst | 2 +-
4 files changed, 239 insertions(+), 61 deletions(-)
diff --git a/doc/configuration.rst b/doc/configuration.rst
index 5b2598cb92d..2a96d8b058e 100644
--- a/doc/configuration.rst
+++ b/doc/configuration.rst
@@ -34,12 +34,11 @@ This defines the database that CKAN is to use. The format is::
Front-End Settings
------------------
-
.. index::
- single: site_title
+ single: ckan.site_title
-site_title
-^^^^^^^^^^
+ckan.site_title
+^^^^^^^^^^^^^^^
Example::
@@ -49,8 +48,11 @@ Default value: ``CKAN``
This sets the name of the site, as displayed in the CKAN web interface.
-site_description
-^^^^^^^^^^^^^^^^
+.. index::
+ single: ckan.site_description
+
+ckan.site_description
+^^^^^^^^^^^^^^^^^^^^^
Example::
@@ -61,10 +63,10 @@ Default value: (none)
This is for a description, or tag line for the site, as displayed in the header of the CKAN web interface.
.. index::
- single: site_logo
+ single: ckan.site_logo
-site_logo
-^^^^^^^^^
+ckan.site_logo
+^^^^^^^^^^^^^^
Example::
@@ -74,8 +76,11 @@ Default value: (none)
This sets the logo used in the title bar.
-site_about
-^^^^^^^^^^
+.. index::
+ single: ckan.site_about
+
+ckan.site_about
+^^^^^^^^^^^^^^^
Example::
@@ -112,8 +117,25 @@ Format tips:
.. note:: Whilst the default text is translated into many languages (switchable in the page footer), the text in this configuration option will not be translatable.
For this reason, it's better to overload the snippet in ``home/snippets/about_text.html``. For more information, see :doc:`theming`.
-favicon
-^^^^^^^
+.. index::
+ single: ckan.main_css
+
+ckan.main_css
+^^^^^^^^^^^^^
+
+Example::
+
+ ckan.main_css = /base/css/my-custom.css
+
+Default value: ``/base/css/main.css``
+
+With this option, instead of using the default `main.css`, you can use your own.
+
+.. index::
+ single: ckan.favicon
+
+ckan.favicon
+^^^^^^^^^^^^
Example::
@@ -124,10 +146,10 @@ Default value: ``/images/icons/ckan.ico``
This sets the site's `favicon`. This icon is usually displayed by the browser in the tab heading and bookmark.
.. index::
- single: ckan.feeds.author_name
+ single: ckan.datasets_per_page
-datasets_per_page
-^^^^^^^^^^^^^^^^^
+ckan.datasets_per_page
+^^^^^^^^^^^^^^^^^^^^^^
Example::
@@ -138,6 +160,9 @@ Default value: ``20``
This controls the pagination of the dataset search results page. This is the maximum number of datasets viewed per page of results.
+.. index::
+ single: package_hide_extras
+
package_hide_extras
^^^^^^^^^^^^^^^^^^^
@@ -165,7 +190,7 @@ Default value: true
When set to false, or no, this setting will hide the 'Apps, Ideas, etc' tab on the package read page. If the value is not set, or is set to true or yes, then the tab will shown.
.. index::
- single: rdf_packages
+ single: ckan.activity_list_limit
ckan.activity_list_limit
^^^^^^^^^^^^^^^^^^^^^^^^
@@ -179,6 +204,9 @@ Default value: ``infinite``
This controls the number of activities to show in the Activity Stream. By default, it shows everything.
+.. index::
+ single: ckan.preview.direct
+
ckan.preview.direct
^^^^^^^^^^^^^^^^^^^
@@ -190,6 +218,9 @@ Default value: ``png jpg gif``
Defines the resource formats which should be embedded directly in an `img` tag
when previewing them.
+.. index::
+ single: ckan.preview.loadable
+
ckan.preview.loadable
^^^^^^^^^^^^^^^^^^^^^
@@ -217,10 +248,10 @@ Configure this if you have an RDF store of the same datasets as are in your CKAN
3. A visible RDF link on the page. e.g. ``
.. index::
- single: dumps_url, dumps_format
+ single: ckan.dumps_url, ckan.dumps_format
-dumps_url & dumps_format
-^^^^^^^^^^^^^^^^^^^^^^^^
+ckan.dumps_url & ckan.dumps_format
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Example::
@@ -231,8 +262,11 @@ If there is a page which allows you to download a dump of the entire catalogue t
For more information on using dumpfiles, see :doc:`database-dumps`.
-recaptcha
-^^^^^^^^^
+.. index::
+ single: ckan.recaptcha.publickey, ckan.recaptcha.privatekey
+
+ckan.recaptcha.publickey & ckan.recaptcha.privatekey
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Example::
ckan.recaptcha.publickey = 6Lc...-KLc
@@ -247,6 +281,9 @@ And there is an option for the default expiry time if not specified::
ckan.cache.default_expires = 600
+.. index::
+ single: ckan.feeds.author_name
+
ckan.feeds.author_name
^^^^^^^^^^^^^^^^^^^^^^
@@ -300,9 +337,6 @@ Default value: ``(none)``
A string representing the default date on which the authority_name is owned by the publisher of the feed.
-.. index::
- single: site_description
-
.. index::
ckan.gravatar_default
@@ -318,7 +352,7 @@ Default value: ``identicon``
This controls the default gravatar avatar, in case the user has none.
.. index::
- single: package_hide_extras
+ single: ckan.legacy_templates
ckan.legacy_templates
^^^^^^^^^^^^^^^^^^^^^
@@ -334,7 +368,7 @@ This controls if the legacy genshi templates are used.
.. note:: This is only for legacy code, and shouldn't be used anymore.
Activity Streams Settings
------------------------
+-------------------------
.. index::
single: ckan.activity_streams_enabled
@@ -351,6 +385,21 @@ Default value: ``True``
Turns on and off the activity streams used to track changes on datasets, groups, users, etc
+.. index::
+ single: ckan.activity_streams_email_notifications
+
+ckan.activity_streams_email_notifications
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Example::
+
+ ckan.activity_streams_email_notifications = False
+
+Default value: ``False``
+
+Turns on and off the activity streams' email notifications. You'd also need to setup a cron job to send
+the emails. For more information, visit :ref:`email-notifications`.
+
.. _config-i18n:
Internationalisation Settings
@@ -372,6 +421,9 @@ Use this to specify the locale (language of the text) displayed in the CKAN Web
.. note: In versions of CKAN before 1.5, the settings used for this was variously `lang` or `ckan.locale`, which have now been deprecated in favour of `ckan.locale_default`.
+.. index::
+ single: ckan.locales_offered
+
ckan.locales_offered
^^^^^^^^^^^^^^^^^^^^
@@ -381,7 +433,10 @@ Example::
Default value: (none)
-By default, all locales found in the ckan/i18n directory will be offered to the user. To only offer a subset of these, list them under this option. The ordering of the locales is preserved when offered to the user.
+By default, all locales found in the ``ckan/i18n`` directory will be offered to the user. To only offer a subset of these, list them under this option. The ordering of the locales is preserved when offered to the user.
+
+.. index::
+ single: ckan.locales_filtered_out
ckan.locales_filtered_out
^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -394,6 +449,9 @@ Default value: (none)
If you want to not offer particular locales to the user, then list them here to have them removed from the options.
+.. index::
+ single: ckan.locale_order
+
ckan.locale_order
^^^^^^^^^^^^^^^^^
@@ -405,6 +463,20 @@ Default value: (none)
If you want to specify the ordering of all or some of the locales as they are offered to the user, then specify them here in the required order. Any locales that are available but not specified in this option, will still be offered at the end of the list.
+.. index::
+ single: ckan.i18n_directory
+
+ckan.i18n_directory
+^^^^^^^^^^^^^^^^^^^
+
+Example::
+
+ ckan.i18n_directory = /opt/locales/i18n/
+
+Default value: (none)
+
+By default, the locales are searched for in the ``ckan/i18n`` directory. Use this option if you want to use another folder.
+
Storage Settings
----------------
@@ -423,6 +495,34 @@ Default value: ``None``
This setting will change the bucket name for the uploaded files.
+.. index::
+ single: ckan.storage.key_prefix
+
+ckan.storage.key_prefix
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Example::
+
+ ckan.storage.key_prefix = ckan-file/
+
+Default value: ``file/``
+
+This setting will change the prefix for the uploaded files.
+
+.. index::
+ single: ckan.storage.max_content_length
+
+ckan.storage.max_content_length
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Example::
+
+ ckan.storage.max_content_length = 500000
+
+Default value: ``50000000``
+
+This defines the maximum content size, in bytes, for uploads.
+
.. index::
single: ofs.storage_dir
@@ -451,14 +551,26 @@ Default value: ``None``
Controls if we're caching CKAN's static files, if it's serving them.
+ckan.static_max_age
+^^^^^^^^^^^^^^^^^^^
+
+Example::
+
+ ckan.static_max_age = 2592000
+
+Default value: ``3600``
+
+Controls CKAN static files' cache max age, if we're serving and caching them.
+
+
Theming Settings
----------------
.. index::
- single: extra_template_paths
+ single: ckan.template_head_end
-template_head_end
-^^^^^^^^^^^^^^^^^
+ckan.template_head_end
+^^^^^^^^^^^^^^^^^^^^^^
HTML content to be inserted just before ```` tag (e.g. extra stylesheet)
@@ -474,8 +586,11 @@ You can also have multiline strings. Just indent following lines. e.g.::
.. note:: This is only for legacy code, and shouldn't be used anymore.
-template_footer_end
-^^^^^^^^^^^^^^^^^^^
+.. index::
+ single: ckan.template_footer_end
+
+ckan.template_footer_end
+^^^^^^^^^^^^^^^^^^^^^^^^
HTML content to be inserted just before ``