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 ```` tag (e.g. Google Analytics code). @@ -496,6 +611,9 @@ Example (showing insertion of Google Analytics code):: .. note:: This is only for legacy code, and shouldn't be used anymore. +.. index:: + single: extra_template_paths + extra_template_paths ^^^^^^^^^^^^^^^^^^^^ @@ -634,8 +752,11 @@ These are the setup parameters for AMQP messaging. These only apply if the messa Search Settings --------------- -simple_search -^^^^^^^^^^^^^ +.. index:: + single: ckan.simple_search + +ckan.simple_search +^^^^^^^^^^^^^^^^^^ Example:: @@ -644,8 +765,9 @@ Example:: 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 + single: ckan.site-id ckan.site_id ^^^^^^^^^^^^ @@ -660,10 +782,7 @@ a single CKAN instance then this can be ignored. Note, if you change this value, you need to rebuild the search index. -.. index:: - single: solr_url - -.. _solr_url: +.. _solr-url: solr_url ^^^^^^^^ @@ -696,6 +815,9 @@ to occur asynchronously, set this option to 0. Note, this is equivalent to explicitly load the `synchronous_search` plugin. +.. index:: + single: ckan.search.solr_commit + ckan.search.solr_commit ^^^^^^^^^^^^^^^^^^^^^^^ @@ -722,6 +844,9 @@ Default value: ``None`` List of the extra resource fields that would be used when searching. +.. index:: + single: ckan.search.show_all_types + ckan.search.show_all_types ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -740,10 +865,10 @@ Site Settings ------------- .. index:: - single: site_url + single: ckan.site_url -site_url -^^^^^^^^ +ckan.site_url +^^^^^^^^^^^^^ Example:: @@ -754,10 +879,10 @@ 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 + single: ckan.api_url -api_url -^^^^^^^ +ckan.api_url +^^^^^^^^^^^^ Example:: @@ -769,6 +894,9 @@ 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: apikey_header_name + apikey_header_name ^^^^^^^^^^^^^^^^^^ @@ -794,6 +922,52 @@ Default value: ``None`` This controls where the error messages will be sent to. +.. index:: + single: ckan.cache_expires + +ckan.cache_expires +^^^^^^^^^^^^^^^^^^ + +Example:: + + ckan.cache_expires = 2592000 + +Default value: '' + +This sets ``Cache-Control`` header's max-age value. + +.. index:: + single: ckan.page_cache_enable + +ckan.page_cache_enable +^^^^^^^^^^^^^^^^^^^^^^ + +Example:: + + ckan.page_cache_enable = True + +Default value: '' + +This enables the page caching. + +.. index:: + single: moderated + +moderated +^^^^^^^^^ + +Example:: + + moderated = True + +Default value: (none) + +This controls if new datasets will require moderation approval before going public. + + +Authorization Settings +---------------------- + .. index:: single: error_email_from @@ -848,10 +1022,10 @@ Plugin Settings --------------- .. index:: - single: plugins + single: ckan.plugins -plugins -^^^^^^^ +ckan.plugins +^^^^^^^^^^^^ Example:: @@ -898,10 +1072,10 @@ Directory Settings ------------------ .. index:: - single: log_dir + single: ckan.log_dir -log_dir -^^^^^^^ +ckan.log_dir +^^^^^^^^^^^^ Example:: @@ -912,10 +1086,10 @@ This is the directory to which CKAN cron scripts (if there are any installed) sh .. note:: This setting is nothing to do with the main CKAN log file, whose filepath is set in the ``[handler_file]`` args. .. index:: - single: dump_dir + single: ckan.dump_dir -dump_dir -^^^^^^^^ +ckan.dump_dir +^^^^^^^^^^^^^ Example:: @@ -926,10 +1100,10 @@ This is the directory to which JSON or CSV dumps of the database are to be writt .. note:: It is usual to set up the Apache config to serve this directory. .. index:: - single: backup_dir + single: ckan.backup_dir -backup_dir -^^^^^^^^^^ +ckan.backup_dir +^^^^^^^^^^^^^^^ Example:: diff --git a/doc/email-notifications.rst b/doc/email-notifications.rst index 52aa7eb2114..90b8beb4c35 100644 --- a/doc/email-notifications.rst +++ b/doc/email-notifications.rst @@ -1,3 +1,5 @@ +.. _email-notifications: + ================================= Send Email Notifications to Users ================================= diff --git a/doc/filestore.rst b/doc/filestore.rst index f2c75a1ff6d..d1516f0a77a 100644 --- a/doc/filestore.rst +++ b/doc/filestore.rst @@ -18,8 +18,10 @@ line in your CKAN config file:: ckan.storage.bucket = my-bucket-name ## Optional - ## maximum content size for uploads in bytes, defaults to 1Gb - # ckanext.storage.max_content_length = 1000000000 + ## prefix for uploaded files' keys + # ckan.storage.key_prefix = ckan-file/ + ## maximum content size for uploads in bytes, defaults to 50 GB + # ckan.storage.max_content_length = 1000000000 Local File Storage ------------------ diff --git a/doc/solr-setup.rst b/doc/solr-setup.rst index ad447fd4682..840756f679e 100644 --- a/doc/solr-setup.rst +++ b/doc/solr-setup.rst @@ -261,4 +261,4 @@ When a new version of the schema becomes available, a new core is created, with latest schema.xml file in the CKAN source. That way, CKAN instances that use an older version of the schema can still point to the core that uses it, while more recent versions can point to the latest one. When old versions of CKAN are updated, they only need to change their -:ref:`solr_url` setting to point to the suitable Solr core. +:ref:`solr-url` setting to point to the suitable Solr core. From 3153b2ee3cd755a70274a696d97a124d5242987d Mon Sep 17 00:00:00 2001 From: Vitor Baptista Date: Mon, 22 Apr 2013 17:39:20 -0300 Subject: [PATCH 4/8] [#534] Remove useless indexes in configuration page --- doc/configuration.rst | 192 ------------------------------------------ 1 file changed, 192 deletions(-) diff --git a/doc/configuration.rst b/doc/configuration.rst index 2a96d8b058e..ea2a66e0dcf 100644 --- a/doc/configuration.rst +++ b/doc/configuration.rst @@ -1,6 +1,3 @@ -.. index:: - single: config file - ===================================== Reference: CKAN Configuration Options ===================================== @@ -16,9 +13,6 @@ The file is well-documented, but we recommend reading this section in full to le Database Settings ----------------- -.. index:: - single: sqlalchemy.url - sqlalchemy.url ^^^^^^^^^^^^^^ @@ -34,9 +28,6 @@ This defines the database that CKAN is to use. The format is:: Front-End Settings ------------------ -.. index:: - single: ckan.site_title - ckan.site_title ^^^^^^^^^^^^^^^ @@ -48,9 +39,6 @@ Default value: ``CKAN`` This sets the name of the site, as displayed in the CKAN web interface. -.. index:: - single: ckan.site_description - ckan.site_description ^^^^^^^^^^^^^^^^^^^^^ @@ -62,9 +50,6 @@ 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: ckan.site_logo - ckan.site_logo ^^^^^^^^^^^^^^ @@ -76,9 +61,6 @@ Default value: (none) This sets the logo used in the title bar. -.. index:: - single: ckan.site_about - ckan.site_about ^^^^^^^^^^^^^^^ @@ -117,9 +99,6 @@ 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`. -.. index:: - single: ckan.main_css - ckan.main_css ^^^^^^^^^^^^^ @@ -131,9 +110,6 @@ 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 ^^^^^^^^^^^^ @@ -145,9 +121,6 @@ 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.datasets_per_page - ckan.datasets_per_page ^^^^^^^^^^^^^^^^^^^^^^ @@ -160,9 +133,6 @@ 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 ^^^^^^^^^^^^^^^^^^^ @@ -189,9 +159,6 @@ 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: ckan.activity_list_limit - ckan.activity_list_limit ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -204,9 +171,6 @@ 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 ^^^^^^^^^^^^^^^^^^^ @@ -218,9 +182,6 @@ 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 ^^^^^^^^^^^^^^^^^^^^^ @@ -247,9 +208,6 @@ 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: ckan.dumps_url, ckan.dumps_format - ckan.dumps_url & ckan.dumps_format ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -262,9 +220,6 @@ 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`. -.. index:: - single: ckan.recaptcha.publickey, ckan.recaptcha.privatekey - ckan.recaptcha.publickey & ckan.recaptcha.privatekey ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -281,9 +236,6 @@ 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 ^^^^^^^^^^^^^^^^^^^^^^ @@ -295,9 +247,6 @@ 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 ^^^^^^^^^^^^^^^^^^^^^^ @@ -309,9 +258,6 @@ 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 ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -323,9 +269,6 @@ 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 ^^^^^^^^^^^^^^^ @@ -337,9 +280,6 @@ Default value: ``(none)`` A string representing the default date on which the authority_name is owned by the publisher of the feed. -.. index:: - ckan.gravatar_default - ckan.gravatar_default ^^^^^^^^^^^^^^^^^^^^^ @@ -351,9 +291,6 @@ Default value: ``identicon`` This controls the default gravatar avatar, in case the user has none. -.. index:: - single: ckan.legacy_templates - ckan.legacy_templates ^^^^^^^^^^^^^^^^^^^^^ @@ -370,9 +307,6 @@ This controls if the legacy genshi templates are used. Activity Streams Settings ------------------------- -.. index:: - single: ckan.activity_streams_enabled - ckan.activity_streams_enabled ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -385,9 +319,6 @@ 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -405,9 +336,6 @@ the emails. For more information, visit :ref:`email-notifications`. Internationalisation Settings ----------------------------- -.. index:: - single: ckan.locale_default - ckan.locale_default ^^^^^^^^^^^^^^^^^^^ @@ -421,9 +349,6 @@ 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 ^^^^^^^^^^^^^^^^^^^^ @@ -435,9 +360,6 @@ 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. -.. index:: - single: ckan.locales_filtered_out - ckan.locales_filtered_out ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -449,9 +371,6 @@ 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 ^^^^^^^^^^^^^^^^^ @@ -463,9 +382,6 @@ 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 ^^^^^^^^^^^^^^^^^^^ @@ -481,9 +397,6 @@ By default, the locales are searched for in the ``ckan/i18n`` directory. Use thi Storage Settings ---------------- -.. index:: - single: ckan.storage.bucket - ckan.storage.bucket ^^^^^^^^^^^^^^^^^^^ @@ -495,9 +408,6 @@ Default value: ``None`` This setting will change the bucket name for the uploaded files. -.. index:: - single: ckan.storage.key_prefix - ckan.storage.key_prefix ^^^^^^^^^^^^^^^^^^^^^^^ @@ -509,9 +419,6 @@ 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -523,9 +430,6 @@ Default value: ``50000000`` This defines the maximum content size, in bytes, for uploads. -.. index:: - single: ofs.storage_dir - ofs.storage_dir ^^^^^^^^^^^^^^^ @@ -537,9 +441,6 @@ 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. -.. index:: - single: ckan.cache_enabled - ckan.cache_enabled ^^^^^^^^^^^^^^^^^^ @@ -566,9 +467,6 @@ Controls CKAN static files' cache max age, if we're serving and caching them. Theming Settings ---------------- -.. index:: - single: ckan.template_head_end - ckan.template_head_end ^^^^^^^^^^^^^^^^^^^^^^ @@ -586,9 +484,6 @@ 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. -.. index:: - single: ckan.template_footer_end - ckan.template_footer_end ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -611,9 +506,6 @@ Example (showing insertion of Google Analytics code):: .. note:: This is only for legacy code, and shouldn't be used anymore. -.. index:: - single: extra_template_paths - extra_template_paths ^^^^^^^^^^^^^^^^^^^^ @@ -627,9 +519,6 @@ 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 ^^^^^^^^^^^^^^^^^^ @@ -647,9 +536,6 @@ For more information on theming, see :doc:`theming`. Form Settings ------------- -.. index:: - single: package_form - package_form ^^^^^^^^^^^^ @@ -667,9 +553,6 @@ The value for this setting can be a Formalchemy form defined in the core CKAN co For more information on forms, see :doc:`forms`. -.. index:: - single: package_new_return_url, package_edit_return_url - .. _config-package-urls: package_new_return_url & package_edit_return_url @@ -685,9 +568,6 @@ If integrating the Edit Dataset and New Dataset forms into a third-party interfa The ```` string is replaced with the name of the dataset edited. Full details of this process are given in :doc:`form-integration`. -.. index:: - single: licenses_group_url - licenses_group_url ^^^^^^^^^^^^^^^^^^ @@ -712,9 +592,6 @@ Examples:: Messaging Settings ------------------ -.. index:: - single: carrot_messaging_library - carrot_messaging_library ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -734,9 +611,6 @@ This is the messaging library backend to use. Options:: See the `Carrot documentation `_ for details. -.. index:: - single: amqp_hostname, amqp_port, amqp_user_id, amqp_password - amqp_hostname, amqp_port, amqp_user_id, amqp_password ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -752,9 +626,6 @@ These are the setup parameters for AMQP messaging. These only apply if the messa Search Settings --------------- -.. index:: - single: ckan.simple_search - ckan.simple_search ^^^^^^^^^^^^^^^^^^ @@ -766,9 +637,6 @@ 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 - ckan.site_id ^^^^^^^^^^^^ @@ -799,9 +667,6 @@ Optionally, ``solr_user`` and ``solr_password`` can also be configured to specif Note, if you change this value, you need to rebuild the search index. -.. index:: - single: ckan.search.automatic_indexing - ckan.search.automatic_indexing ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -815,9 +680,6 @@ to occur asynchronously, set this option to 0. Note, this is equivalent to explicitly load the `synchronous_search` plugin. -.. index:: - single: ckan.search.solr_commit - ckan.search.solr_commit ^^^^^^^^^^^^^^^^^^^^^^^ @@ -829,9 +691,6 @@ 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). -.. index:: - single: ckan.extra_resource_fields - ckan.extra_resource_fields ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -844,9 +703,6 @@ Default value: ``None`` List of the extra resource fields that would be used when searching. -.. index:: - single: ckan.search.show_all_types - ckan.search.show_all_types ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -864,9 +720,6 @@ standard datasets. Site Settings ------------- -.. index:: - single: ckan.site_url - ckan.site_url ^^^^^^^^^^^^^ @@ -878,9 +731,6 @@ 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: ckan.api_url - ckan.api_url ^^^^^^^^^^^^ @@ -894,9 +744,6 @@ 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: apikey_header_name - apikey_header_name ^^^^^^^^^^^^^^^^^^ @@ -908,9 +755,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. -.. index:: - single: email_to - email_to ^^^^^^^^ @@ -922,9 +766,6 @@ Default value: ``None`` This controls where the error messages will be sent to. -.. index:: - single: ckan.cache_expires - ckan.cache_expires ^^^^^^^^^^^^^^^^^^ @@ -936,9 +777,6 @@ Default value: '' This sets ``Cache-Control`` header's max-age value. -.. index:: - single: ckan.page_cache_enable - ckan.page_cache_enable ^^^^^^^^^^^^^^^^^^^^^^ @@ -950,9 +788,6 @@ Default value: '' This enables the page caching. -.. index:: - single: moderated - moderated ^^^^^^^^^ @@ -968,9 +803,6 @@ This controls if new datasets will require moderation approval before going publ Authorization Settings ---------------------- -.. index:: - single: error_email_from - error_email_from ^^^^^^^^^^^^^^^^ @@ -982,9 +814,6 @@ Default value: ``None`` This controls from which email the error messages will come from. -.. index:: - single: debug - debug ^^^^^ @@ -1001,9 +830,6 @@ files, and enables CKAN templates' debugging features. Debug mode will enable the interactive debugging tool, allowing ANYONE to execute malicious code after an exception is raised. -.. index:: - single: ckan.debug_supress_header - ckan.debug_supress_header ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1021,9 +847,6 @@ receiving the request being is shown in the header. Plugin Settings --------------- -.. index:: - single: ckan.plugins - ckan.plugins ^^^^^^^^^^^^ @@ -1037,9 +860,6 @@ 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 ^^^^^^^^^^^^^^^^^^^^^^ @@ -1053,9 +873,6 @@ Controls if the Data API link will appear in Dataset's Resource page. .. note:: This setting only applies to the legacy templates. -.. index:: - single: ckanext.stats.cache_enabled - ckanext.stats.cache_enabled ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1071,9 +888,6 @@ This controls if we'll use the 1 day cache for stats. Directory Settings ------------------ -.. index:: - single: ckan.log_dir - ckan.log_dir ^^^^^^^^^^^^ @@ -1085,9 +899,6 @@ This is the directory to which CKAN cron scripts (if there are any installed) sh .. note:: This setting is nothing to do with the main CKAN log file, whose filepath is set in the ``[handler_file]`` args. -.. index:: - single: ckan.dump_dir - ckan.dump_dir ^^^^^^^^^^^^^ @@ -1099,9 +910,6 @@ This is the directory to which JSON or CSV dumps of the database are to be writt .. note:: It is usual to set up the Apache config to serve this directory. -.. index:: - single: ckan.backup_dir - ckan.backup_dir ^^^^^^^^^^^^^^^ From b515fe7489251ddb5520d79f537d8e9998405e96 Mon Sep 17 00:00:00 2001 From: Vitor Baptista Date: Mon, 22 Apr 2013 17:42:43 -0300 Subject: [PATCH 5/8] [#534] Minor styling adjustements --- doc/configuration.rst | 43 +++++++++++++++++++++---------------------- 1 file changed, 21 insertions(+), 22 deletions(-) diff --git a/doc/configuration.rst b/doc/configuration.rst index ea2a66e0dcf..40bddbd80fe 100644 --- a/doc/configuration.rst +++ b/doc/configuration.rst @@ -10,6 +10,7 @@ The file is well-documented, but we recommend reading this section in full to le .. note:: The CKAN config file also includes general Pylons options. All CKAN-specific settings are in the `[app:main]` section. + Database Settings ----------------- @@ -33,7 +34,7 @@ ckan.site_title Example:: - ckan.site_title=Open Data Scotland + ckan.site_title = Open Data Scotland Default value: ``CKAN`` @@ -66,7 +67,7 @@ ckan.site_about Example:: - ckan.site_about=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:: @@ -132,7 +133,6 @@ 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 ^^^^^^^^^^^^^^^^^^^ @@ -170,7 +170,6 @@ Default value: ``infinite`` This controls the number of activities to show in the Activity Stream. By default, it shows everything. - ckan.preview.direct ^^^^^^^^^^^^^^^^^^^ @@ -235,7 +234,6 @@ And there is an option for the default expiry time if not specified:: ckan.cache.default_expires = 600 - ckan.feeds.author_name ^^^^^^^^^^^^^^^^^^^^^^ @@ -304,6 +302,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 ------------------------- @@ -318,7 +317,6 @@ Default value: ``True`` Turns on and off the activity streams used to track changes on datasets, groups, users, etc - ckan.activity_streams_email_notifications ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -331,6 +329,7 @@ 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 @@ -341,7 +340,7 @@ ckan.locale_default Example:: - ckan.locale_default=de + ckan.locale_default = de Default value: ``en`` (English) @@ -354,7 +353,7 @@ ckan.locales_offered Example:: - ckan.locales_offered=en de fr + ckan.locales_offered = en de fr Default value: (none) @@ -365,7 +364,7 @@ ckan.locales_filtered_out Example:: - ckan.locales_filtered_out=pl ru + ckan.locales_filtered_out = pl ru Default value: (none) @@ -376,7 +375,7 @@ ckan.locale_order Example:: - ckan.locale_order=fr de + ckan.locale_order = fr de Default value: (none) @@ -511,7 +510,7 @@ extra_template_paths Example:: - extra_template_paths=/home/okfn/brazil_ckan_config/templates + 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 (,). @@ -567,7 +566,6 @@ If integrating the Edit Dataset and New Dataset forms into a third-party interfa The ```` string is replaced with the name of the dataset edited. Full details of this process are given in :doc:`form-integration`. - licenses_group_url ^^^^^^^^^^^^^^^^^^ @@ -597,7 +595,7 @@ carrot_messaging_library Example:: - carrot_messaging_library=pyamqplib + carrot_messaging_library = pyamqplib This is the messaging library backend to use. Options:: @@ -611,18 +609,19 @@ This is the messaging library backend to use. Options:: See the `Carrot documentation `_ for details. -amqp_hostname, amqp_port, amqp_user_id, amqp_password -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +amqp_hostname & amqp_port & amqp_user_id & amqp_password +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Example:: - amqp_hostname=localhost - amqp_port=5672 - amqp_user_id=guest - amqp_password=guest + amqp_hostname = localhost + amqp_port = 5672 + amqp_user_id = guest + amqp_password = guest These are the setup parameters for AMQP messaging. These only apply if the messaging library has been set to use AMQP (see `carrot_messaging_library`_). The values given above are the default values. + Search Settings --------------- @@ -702,7 +701,6 @@ Default value: ``None`` List of the extra resource fields that would be used when searching. - ckan.search.show_all_types ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -725,7 +723,7 @@ ckan.site_url Example:: - ckan.site_url=http://scotdata.ckan.net + ckan.site_url = http://scotdata.ckan.net Default value: (none) @@ -736,7 +734,7 @@ ckan.api_url Example:: - ckan.api_url=http://scotdata.ckan.net/api + ckan.api_url = http://scotdata.ckan.net/api Default value: ``/api`` @@ -844,6 +842,7 @@ receiving the request being is shown in the header. .. note:: This info only shows if debug is set to True. + Plugin Settings --------------- From b6e4daec4274a4d7dd113d6b5022040db9e04600 Mon Sep 17 00:00:00 2001 From: Vitor Baptista Date: Mon, 22 Apr 2013 17:47:06 -0300 Subject: [PATCH 6/8] [#534] Remove unused configuration flags --- ckan/config/deployment.ini_tmpl | 3 --- doc/configuration.rst | 19 ------------------- test-core.ini | 2 -- 3 files changed, 24 deletions(-) diff --git a/ckan/config/deployment.ini_tmpl b/ckan/config/deployment.ini_tmpl index 8ab9dac4083..558f9cdd735 100644 --- a/ckan/config/deployment.ini_tmpl +++ b/ckan/config/deployment.ini_tmpl @@ -79,9 +79,6 @@ who.config_file = %(here)s/who.ini who.log_level = warning who.log_file = %(cache_dir)s/who_log.ini -# Location of RDF versions of datasets -#rdf_packages = http://semantic.ckan.net/record/ - # Location of licenses group (defaults to cached local version of ckan group) #licenses_group_url = http://licenses.opendefinition.org/licenses/groups/ckan.json diff --git a/doc/configuration.rst b/doc/configuration.rst index 40bddbd80fe..310feebaca9 100644 --- a/doc/configuration.rst +++ b/doc/configuration.rst @@ -192,21 +192,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. -rdf_packages -^^^^^^^^^^^^ - -Example:: - - rdf_packages = http://semantic.ckan.net/record/ - -Configure this if you have an RDF store of the same datasets as are in your CKAN instance. It will provide three sorts of links from each dataset page to the equivalent RDF URL given in `rdf_packages`: - -1. 303 redirects for clients that content-negotiate rdf-xml or turtle. e.g. client GETs `http://ckan.net/dataset/pollution-2008` with accept header `application/rdf+xml` ``curl -H "Accept: application/rdf+xml" http://ckan.net/dataset/pollution-2008``. CKAN's response is a 303 redirect to `http://semantic.ckan.net/dataset/pollution-2008` which can be obtained with: ``curl -L -H "Accept: application/rdf+xml" http://ckan.net/dataset/pollution-2008`` - -2. Embedded links for browsers that are aware. e.g. `` - -3. A visible RDF link on the page. e.g. `` - ckan.dumps_url & ckan.dumps_format ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -230,10 +215,6 @@ Setting both these options according to an established Recaptcha account adds ca To get a Recaptcha account, sign up at: http://www.google.com/recaptcha -And there is an option for the default expiry time if not specified:: - - ckan.cache.default_expires = 600 - ckan.feeds.author_name ^^^^^^^^^^^^^^^^^^^^^^ diff --git a/test-core.ini b/test-core.ini index d4372d234c2..dfa2f014f70 100644 --- a/test-core.ini +++ b/test-core.ini @@ -25,7 +25,6 @@ ckan.auth.create_unowned_dataset=true ckan.cache_validation_enabled = True ckan.cache_enabled = False -ckan.cache.default_expires = 200 ckan.tests.functional.test_cache.expires = 1800 ckan.tests.functional.test_cache.TestCacheBasics.test_get_cache_expires.expires = 3600 @@ -40,7 +39,6 @@ carrot_messaging_library = queue ckan.site_url = http://test.ckan.net package_new_return_url = http://localhost/dataset/?test=new package_edit_return_url = http://localhost/dataset/?test=edit -rdf_packages = http://test.com/package/ ckan.extra_resource_fields = alt_url # we need legacy templates for many tests to pass From 62a39b86b42964a2e89165ab564ff5cb55b7a995 Mon Sep 17 00:00:00 2001 From: Vitor Baptista Date: Tue, 23 Apr 2013 23:05:02 -0300 Subject: [PATCH 7/8] [#534] Document some undocumented config options The added options are: ckan.tracking_enabled search.facet.limits ckan.root_path ckan.site_intro_text --- doc/configuration.rst | 90 +++++++++++++++++++++++++++++++++---------- doc/i18n.rst | 2 +- 2 files changed, 70 insertions(+), 22 deletions(-) diff --git a/doc/configuration.rst b/doc/configuration.rst index 310feebaca9..93c75339727 100644 --- a/doc/configuration.rst +++ b/doc/configuration.rst @@ -51,6 +51,17 @@ Default value: (none) This is for a description, or tag line for the site, as displayed in the header of the CKAN web interface. +ckan.site_intro_text +^^^^^^^^^^^^^^^^^^^^ + +Example:: + + ckan.site_intro_text = Nice introductory paragraph about CKAN or the site in general. + +Default value: (none) + +This is for an introductory text used in the default template's index page. + ckan.site_logo ^^^^^^^^^^^^^^ @@ -373,6 +384,22 @@ 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. +.. _ckan_root_path: + +ckan.root_path +^^^^^^^^^^^^^^ + +Example:: + + ckan.root_path = /my/custom/path/{{LANG}}/foo + +Default value: (none) + +By default, the URLs are formatted as ``/some/url``, when using the default +locale, or ``/de/some/url`` when using the "de" locale, for example. This +lets you change this. You can use any path that you want, adding ``{{LANG}}`` +where you want the locale code to go. + Storage Settings ---------------- @@ -606,17 +633,6 @@ These are the setup parameters for AMQP messaging. These only apply if the messa Search Settings --------------- -ckan.simple_search -^^^^^^^^^^^^^^^^^^ - -Example:: - - 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. - ckan.site_id ^^^^^^^^^^^^ @@ -630,6 +646,17 @@ a single CKAN instance then this can be ignored. Note, if you change this value, you need to rebuild the search index. +ckan.simple_search +^^^^^^^^^^^^^^^^^^ + +Example:: + + 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. + .. _solr-url: solr_url @@ -671,29 +698,39 @@ 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.extra_resource_fields +ckan.search.show_all_types ^^^^^^^^^^^^^^^^^^^^^^^^^^ Example:: - ckan.extra_resource_fields = alt_url + ckan.search.show_all_types = true -Default value: ``None`` +Default value: ``false`` -List of the extra resource fields that would be used when searching. +Controls whether the default search page (``/dataset``) should show only +standard datasets or also custom dataset types. -ckan.search.show_all_types +search.facet.limits +^^^^^^^^^^^^^^^^^^^ + +Example:: + + search.facet.limits = 100 + +Default value: ``50`` + +Sets the default number of searched facets returned in a query. + +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. Site Settings @@ -778,6 +815,17 @@ Default value: (none) This controls if new datasets will require moderation approval before going public. +ckan.tracking_enabled +--------------------- + +Example:: + + ckan.tracking_enabled = True + +Default value: ``False`` + +This controls if CKAN will track the site usage. + Authorization Settings ---------------------- diff --git a/doc/i18n.rst b/doc/i18n.rst index 73615259ee7..48860880209 100644 --- a/doc/i18n.rst +++ b/doc/i18n.rst @@ -6,7 +6,7 @@ Internationalize CKAN CKAN is used in many countries, and adding a new language to the web interface is a simple process. -CKAN uses the url to determine which language is used. An example would be ``/fr/dataset`` would be shown in french. If CKAN is running under a directory then an example would be ``/root/fr/dataset``. For custom paths the ``ckan.root_path`` config option can be used and is of the form ``/path/from/root/with/{{LANG}}/substitution``. +CKAN uses the url to determine which language is used. An example would be ``/fr/dataset`` would be shown in french. If CKAN is running under a directory then an example would be ``/root/fr/dataset``. For custom paths check the :ref:`ckan_root_path` config option. .. Note: Storing metadata field values in more than one language is a separate topic. This is achieved by storing the translations in extra fields. A custom dataset form and dataset display template are recommended. Ask the CKAN team for more information. From a4bffcb23473a6cb88a39af3b5229e8e86c2372c Mon Sep 17 00:00:00 2001 From: Vitor Baptista Date: Thu, 25 Apr 2013 16:39:30 -0300 Subject: [PATCH 8/8] [#534] Add E-mail Settings section and add cross-references to the config options. --- doc/configuration.rst | 120 +++++++++++++++++++++++++++++------- doc/email-notifications.rst | 14 ++--- doc/tracking.rst | 4 +- 3 files changed, 107 insertions(+), 31 deletions(-) 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]