534 update config options docs #833
Conversation
These ones are no longer used and will just confuse: * package_form * carrot_messaging_library * amqp_hostname & amqp_port & amqp_user_id & amqp_password * ckan.log_dir * ckan.dump_dir * ckan.backup_dir Also some minor formatting fixes.
Sections rearranged by importance/usage and items put to their relevant one. Sections are now: *General Settings * Database Settings * Site Settings * Search Settings * Plugin Settings * Front-End Settings * Theming Settings * Activity Streams Settings * Feeds Settings * Internationalisation Settings * Storage Settings * Form Settings * E-mail Settings
They are one of the most important ones and they should be found on the
conguration options docs. To avoid duplicating them the include rst
directive is used:
.. include:: /configuration.rst
:start-after: start_config-authorization
:end-before: end_config-authorization
This requires setting the two markers on the imported file, eg:
.. start_config-authorization
... stuff to include ...
.. end_config-authorization
|
The include thing works fine: http://docs.ckan.org/en/534-update-config-options-docs/authorization.html |
|
Cool! Didn't know you could include pages like that 👍 |
Make the reST label for cross-referencing each config setting the same as the name of the config setitng itself, e.g. ckan.activity_streams_email_notifications, don't mix and match different styles of ., _ and - like ckan-activity-streams-email-notifications, ckan_activity_streams_email_notifications, etc.
Now we can easily cross-reference any config option from any file in docs/.
Use the default ini file locations; Clarify what the [app:main] section is; say "restart webserver" not Apache, webserver may not be Apache.
|
The include thing is a great trick. Unfortunately now that I've added labels to each of the I've changed the labels for the config settings to be the same as the names of the config options, e.g. I edited the text at the top of the page. I used Sphinx's I'm not sure about breaking the config options up into different sections like Site Settings, Frontend Settings, etc. This may just make it harder because now you have to decide what section an option belongs in. For example, does Also, some settings actually use the setting names to namespace themselves, e.g. I think we can probably just sort all the config options alphabetically, and then we won't need sections, because all the I'll leave the sections in for now, though. |
|
@vitorbaptista Are there any more options that should be documented, deleted from the code, or marked deprecated in the code? See #534 and #693. Once you're satisfied that we've got them all, we can merge this. |
ghost
assigned 
|
@vitorbaptista Are you sure that |
This is used by much more than just the API
Fix typos, and mark the feature as experimental
It's a list of plugins, not a list of extensions
I personally find the sections useful, as the options are not properly namespaced and the list is a bit daunting without them. Also you are likely to want to know about options related to the same thing. |
|
I just noticed that there are lots of undocumented filestore options present in the deployment.ini_tmpl file and not in the configuration option docs: https://github.com/okfn/ckan/blob/master/ckan/config/deployment.ini_tmpl#L245 |
|
Yeah let's keep the sections for now |
|
That's a bit worrying about those filestore settings. How did we miss those? The code accesses them with |
|
I've merged this into master and 2.0 and made a new issue to keep working on this for 2.1: #848 |
Based on #693, see previous discussion there.
@vitorbaptista I've created the PR because I could not push more changes to yours becasue it was based on your repo.
@seanh All looks good, I've cleaned up some options and rearranged the sections more logically. Perhaps the most controversial change is moving the authorization config options to the configuration docs and include them back on the authorizations page to avoid duplication (see 01cd2de for details). I'll try it on RTD to make sure it works