Add documentation to general.yml parameters

Also available at http://alaveteli.org/docs/customising/config

1 files changed, 621 insertions, 117 deletions

diff --git a/config/general.yml-example b/config/general.yml-example
index 112248049..4631170d3 100644
--- a/config/general.yml-example
+++ b/config/general.yml-example
@@ -8,254 +8,758 @@
 #
 # Default values for these settings can be found in
 # RAILS_ROOT/lib/configuration.rb
+#
+# ==============================================================================
 
 # Site name appears in various places throughout the site
+#
+# SITE_NAME - String name of the site (default: 'Alaveteli')
+#
+# Examples:
+#
+#   SITE_NAME: 'Alaveteli'
+#   SITE_NAME: 'WhatDoTheyKnow'
+#
+# ---
 SITE_NAME: 'Alaveteli'
 
 # Domain used in URLs generated by scripts (e.g. for going in some emails)
-DOMAIN: '127.0.0.1:3000'
+#
+# DOMAIN - String domain or IP address (default: 'localhost:3000')
+#
+# Examples:
+#
+#   DOMAIN: '127.0.0.1:3000'
+#   DOMAIN: 'www.example.com'
+#
+# ---
+DOMAIN: 'www.example.org'
 
-# If true forces everyone (in the production environment) to use encrypted connections
-# (via https) by redirecting unencrypted connections. This is *highly* recommended
-# so that logins can't be intercepted by naughty people.
+# If true forces everyone (in the production environment) to use encrypted
+# connections (via https) by redirecting unencrypted connections. This is
+# *highly* recommended so that logins can't be intercepted by naughty people.
+#
+# FORCE_SSL - Boolean (default: true)
+#
+# ---
 FORCE_SSL: true
 
 # ISO country code of country currrently deployed in
 # (http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
+#
+# ISO_COUNTRY_CODE - String country code (default: GB)
+#
+# Examples:
+#
+#   ISO_COUNTRY_CODE: GB
+#
+# ---
 ISO_COUNTRY_CODE: GB
 
 # This is the timezone that times and dates are displayed in
 # If not set defaults to UTC.
-TIME_ZONE: Australia/Sydney
+#
+# TIME_ZONE - String time zone (default: UTC)
+#
+# Examples:
+#
+#   TIME_ZONE: Australia/Sydney
+#   TIME_ZONE: Europe/London
+#
+# ---
+TIME_ZONE: UTC
 
 # These feeds are displayed accordingly on the Alaveteli "blog" page:
-BLOG_FEED: 'https://www.mysociety.org/category/projects/whatdotheyknow/feed/'
-TWITTER_USERNAME: 'whatdotheyknow'
+#
+# BLOG_FEED - String url to the blog feed (default: nil)
+#
+# Examples:
+#
+#   BLOG_FEED: https://www.mysociety.org/category/projects/whatdotheyknow/feed/
+#
+# ---
+BLOG_FEED: ''
+
+# If you want a twitter feed displayed on the "blog" page, provide the
+# widget ID and username.
+#
+# TWITTER_USERNAME - String Twitter username (default: nil)
+#
+# Examples:
+#
+#   TWITTER_USERNAME: 'whatdotheyknow'
+#
+# ---
+TWITTER_USERNAME: ''
+
 # Set the widget_id to get the Twitter sidebar on the blog page.
 # To get one https://twitter.com/settings/widgets
+#
+# TWITTER_WIDGET_ID - String widget ID (default: false)
+#
+# Examples:
+#
+#   TWITTER_WIDGET_ID: '833549204689320031'
+#
+# ---
 TWITTER_WIDGET_ID: ''
 
-# Locales we wish to support in this app, space-delimited
-AVAILABLE_LOCALES: 'en es'
+# The locales you want your site to support. If there is more than one, use
+# spaces betwween the entries.
+#
+# AVAILABLE_LOCALES – String of space-separated locales (default: nil)
+#
+# Examples:
+#
+#   AVAILABLE_LOCALES: 'en es'
+#
+# ---
+AVAILABLE_LOCALES: 'en'
+
+# Nominate one of the AVAILABLE_LOCALES locales as the default
+#
+# DEFAULT_LOCALE – String locale (default: nil)
+#
+# Examples:
+#
+#   DEFAULT_LOCALE: 'en'
+#
+# ---
 DEFAULT_LOCALE: 'en'
+
+# Should Alaveteli try to use the default language of the user's browser?
+#
+# USE_DEFAULT_BROWSER_LANGUAGE - Boolean (default: true)
+#
+# Examples:
+#
+#   USE_DEFAULT_BROWSER_LANGUAGE: true
+#
+# ---
 USE_DEFAULT_BROWSER_LANGUAGE: true
 
-# If you don't want the default locale to be included in URLs generated
-# by the application, set this to false
+# Normally, Alaveteli will put the locale into its URLs, like this
+# www.example.com/en/body/list/all. If you don't want this behaviour whenever
+# the locale is the default one, set INCLUDE_DEFAULT_LOCALE_IN_URLS to false.
+#
+# INCLUDE_DEFAULT_LOCALE_IN_URLS: Boolean (default: true)
+#
+# Examples:
+#
+#   INCLUDE_DEFAULT_LOCALE_IN_URLS: false
+#
+# ---
 INCLUDE_DEFAULT_LOCALE_IN_URLS: true
 
-# How many days should have passed before an answer to a request is officially late?
+# The REPLY...AFTER_DAYS settings define how many days must have passed before
+# an answer to a request is officially late. The SPECIAL case is for some types
+# of authority (for example: in the UK, schools) which are granted a bit longer
+# than everyone else to respond to questions.
+#
+# REPLY_LATE_AFTER_DAYS - Integer (default: 20)
+# REPLY_VERY_LATE_AFTER_DAYS - Integer (default: 40)
+# SPECIAL_REPLY_VERY_LATE_AFTER_DAYS - Integer (default: 60)
+#
+# Examples:
+#
+#   REPLY_LATE_AFTER_DAYS: 20
+#   REPLY_VERY_LATE_AFTER_DAYS: 40
+#   SPECIAL_REPLY_VERY_LATE_AFTER_DAYS: 60
+#
+# ---
 REPLY_LATE_AFTER_DAYS: 20
 REPLY_VERY_LATE_AFTER_DAYS: 40
-# We give some types of authority like schools a bit longer than everyone else
 SPECIAL_REPLY_VERY_LATE_AFTER_DAYS: 60
-# Whether the days above are given in working or calendar days. Value can be "working" or "calendar".
-# Default is "working".
+
+# The WORKING_OR_CALENDAR_DAYS setting can be either "working" (the default) or 
+# "calendar", and determines which days are counted when calculating whether a
+# request is officially late.
+#
+# WORKING_OR_CALENDAR_DAYS - String in [working, calendar] (default: working)
+#
+# Examples:
+#
+#   WORKING_OR_CALENDAR_DAYS: working
+#   WORKING_OR_CALENDAR_DAYS: calendar
+#
+# ---
 WORKING_OR_CALENDAR_DAYS: working
 
-# example public bodies for the home page, semicolon delimited - short_names
-# Comment out if you want this to be auto-generated. WARNING: this is slow & don't use production!
-FRONTPAGE_PUBLICBODY_EXAMPLES: 'tgq'
+# Specify which public bodies you want to be listed as examples on the home
+# page, using their short_names. If you want more than one, separate them with
+# semicolons. List is auto-generated if not set.
+#
+# *Warning:* this is slow — don't use in production!
+#
+# FRONTPAGE_PUBLICBODY_EXAMPLES - String semicolon-separated list of public
+#                                 bodies (default: nil) 
+#
+# Examples:
+#
+#   FRONTPAGE_PUBLICBODY_EXAMPLES: 'tgq'
+#   FRONTPAGE_PUBLICBODY_EXAMPLES: 'tgq;foo;bar'
+#
+# ---
+FRONTPAGE_PUBLICBODY_EXAMPLES: ''
 
-# URLs of themes to download and use (when running rails-post-deploy
-# script). Earlier in the list means the templates have a higher
-# priority.
+# URLs of themes to download and use (when running the rails-post-deploy
+# script). The earlier in the list means the templates have a higher priority.
+#
+# THEME_URLS - Array of theme URLs (default: [])
+#
+# Examples:
+#
+#   THEME_URLS:
+#     - 'git://github.com/mysociety/alavetelitheme.git'
+#     - 'git://github.com/mysociety/whatdotheyknow-theme.git'
+#
+# ---
 THEME_URLS:
- - 'git://github.com/mysociety/alavetelitheme.git'
+  - 'git://github.com/mysociety/alavetelitheme.git'
 
-# When rails-post-deploy installs the themes it will try this branch first
-# (but only if this config is set). If the branch doesn't exist it will fall
-# back to using a tagged version specific to your installed alaveteli version.
-# If that doesn't exist it will back to master.
+# When rails-post-deploy installs the themes, it will try to use the branch
+# specified by THEME_BRANCH first. If the branch doesn't exist it will fall
+# back to using a tagged version specific to your installed alaveteli version,
+# and if that doesn't exist it will fall back to master.
+#
+# THEME_BRANCH - Boolean (default: false)
+#
+# Examples:
+#
+#   # Use the develop branch if it exists, otherwise fall back as described
+#   THEME_BRANCH: 'develop'
+#
+#   # try the use-with-alaveteli-xxx branch/tag, otherwise fall back to HEAD
+#   THEME_BRANCH: false
+#
+# ---
 THEME_BRANCH: false
 
-# Whether a user needs to sign in to start the New Request process
+# Does a user needs to sign in to start the New Request process?
+#
+# FORCE_REGISTRATION_ON_NEW_REQUEST - Boolean (default: false)
+#
+# ---
 FORCE_REGISTRATION_ON_NEW_REQUEST: false
 
-
-## Incoming email
-# Your email domain, e.g. 'foifa.com'
+# Your email domain for incoming mail.
+#
+# INCOMING_EMAIL_DOMAIN – String domain (default: localhost)
+#
+# Examples:
+#
+#   INCOMING_EMAIL_DOMAIN: 'localhost'
+#   INCOMING_EMAIL_DOMAIN: 'foifa.com'
+#
+# ---
 INCOMING_EMAIL_DOMAIN: 'localhost'
 
-# An optional prefix to help you distinguish FOI requests, e.g. 'foi+'
-INCOMING_EMAIL_PREFIX: ''
+# An optional prefix to help you distinguish FOI requests.
+#
+# INCOMING_EMAIL_PREFIX - String (default: nil)
+#
+# Examples:
+#
+#   INCOMING_EMAIL_PREFIX: ''
+#   INCOMING_EMAIL_PREFIX: 'foi+'
+#
+# ---
+INCOMING_EMAIL_PREFIX: 'foi+'
 
-# used for hash in request email address
+# Used for hash in request email address.
+#
+# INCOMING_EMAIL_SECRET - String (default: dummysecret)
+#
+# Examples:
+#
+#   INCOMING_EMAIL_SECRET: '11ae 4e3b 70ff c001 3682 4a51 e86d ef5f'
+#
+# ---
 INCOMING_EMAIL_SECRET: 'xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx'
 
-# used as envelope from at the incoming email domain for cases where we don't care about failure
+# Used as envelope from at the incoming email domain for cases where you don't
+# care about failure.
+#
+# BLACKHOLE_PREFIX - String (default: do-not-reply-to-this-address)
+#
+# Examples:
+#
+#   BLACKHOLE_PREFIX: 'do-not-reply-to-this-address'
+#   BLACKHOLE_PREFIX: 'do-not-reply'
+#
+# ---
 BLACKHOLE_PREFIX: 'do-not-reply-to-this-address'
 
-# The emergency user
+# Emergency admin user login username. You should change this.
+#
+# ADMIN_USERNAME - String (default: nil)
+#
+# Examples:
+#
+#   ADMIN_USERNAME: 'admin-alaveteli'
+#
+# ---
 ADMIN_USERNAME: 'adminxxxx'
+
+# Emergency admin user login password. You should change this.
+#
+# ADMIN_USERNAME - String (default: nil)
+#
+# Examples:
+#
+#   ADMIN_PASSWORD: 'b38bCHBl;28'
+#
+# ---
 ADMIN_PASSWORD: 'passwordx'
+
+# Disable the emergency admin user?
+#
+# DISABLE_EMERGENCY_USER - Boolean (default: false)
+#
+# ---
 DISABLE_EMERGENCY_USER: false
 
-# Set this to true, and the admin interface will be available to anonymous users
+# Set this to true, and the admin interface will be available to anonymous
+# users. Obviously, you should not set this to be true in production
+# environments.
+#
+# SKIP_ADMIN_AUTH - Boolean (default: false)
+#
+# ---
 SKIP_ADMIN_AUTH: false
 
-# Email "from" details
-CONTACT_EMAIL: 'postmaster@localhost'
-CONTACT_NAME: 'Alaveteli Webmaster'
+# Email "from" email address
+#
+# CONTACT_EMAIL: String email address (default: contact@localhost)
+#
+# ---
+CONTACT_EMAIL: 'contact@localhost'
+
+# Email "from" name
+#
+# CONTACT_NAME - String contact name (default: Alaveteli)
+#
+# ---
+CONTACT_NAME: 'Alaveteli'
 
-# Email "from" details for track messages
-TRACK_SENDER_EMAIL: 'postmaster@localhost'
-TRACK_SENDER_NAME: 'Alaveteli Webmaster'
+# Email "from" email address for track messages
+#
+# TRACK_SENDER_EMAIL - String email address (default: contact@localhost)
+#
+# ---
+TRACK_SENDER_EMAIL: 'contact@localhost'
 
-# Where the raw incoming email data gets stored; make sure you back
+# Email "from" name for track messages
+#
+# TRACK_SENDER_NAME - String contact name (default: Alaveteli)
+#
+# ---
+TRACK_SENDER_NAME: 'Alaveteli'
+
+# Directory where the raw incoming email data gets stored; make sure you back
 # this up!
+#
+# RAW_EMAILS_LOCATION - String path (default: files/raw_emails)
+#
+# ---
 RAW_EMAILS_LOCATION: 'files/raw_emails'
 
-# Secret key for signing cookie_store sessions
+# Secret key for signing cookie_store sessions. Make it long and random.
+#
+# COOKIE_STORE_SESSION_SECRET - String (default: 'this default is insecure as
+#                                       code is open source, please override
+#                                       for live sites in config/general; this
+#                                       will do for local development')
+#
+# Examples:
+#
+#   COOKIE_STORE_SESSION_SECRET: 'uIngVC238Jn9NsaQizMNf89pliYmDBFugPjHS2JJmzOp8'
+#
+# ---
 COOKIE_STORE_SESSION_SECRET: 'your secret key here, make it long and random'
 
 # If present, puts the site in read only mode, and uses the text as reason
 # (whole paragraph). Please use a read-only database user as well, as it only
-# checks in a few obvious places.
-READ_ONLY: ''
+# checks in a few obvious places. Typically, you do not want to run your site
+# in read-only mode.
+#
+# READ_ONLY - String (default: nil)
+#
+# Examples:
+#
+#   READ_ONLY: 'The site is not currently accepting requests while we move the
+#   server.'
+#
+# ---
+# READ_ONLY: ''
 
-# Is this a staging or dev site (1) or a live site (0).
-# Controls whether or not the rails-post-deploy script
-# will create the file config/rails_env.rb file to force
-# Rails into production environment.
-STAGING_SITE: 1
+# Is this a staging or development site? If not, it's a live production site.
+# This setting controls whether or not the rails-post-deploy script will create
+# the file config/rails_env.rb file to force Rails into production environment.
+#
+# STAGING_SITE: Integer in [0, 1]
+#
+# Examples:
+#
+#   # For staging or development:
+#   STAGING_SITE: 1
+#
+#   # For production:
+#   STAGING_SITE: 0
+#
+# ---
+STAGING_SITE: 0
 
-# Recaptcha, for detecting humans. Get keys here: http://recaptcha.net/whyrecaptcha.html
+# Recaptcha, for detecting humans. Get keys here:
+# http://recaptcha.net/whyrecaptcha.html
+#
+# RECAPTCHA_PUBLIC_KEY - String (default: 'x')
+#
+# ---
 RECAPTCHA_PUBLIC_KEY: 'x'
+
+# Recaptcha, for detecting humans. Get keys here:
+# http://recaptcha.net/whyrecaptcha.html
+#
+# RECAPTCHA_PRIVATE_KEY - String (default: 'x')
+#
+# ---
 RECAPTCHA_PRIVATE_KEY: 'x'
 
 # Number of days after which to send a 'new response reminder'
+#
+# NEW_RESPONSE_REMINDER_AFTER_DAYS – Array of Integers (default: [3, 10, 24])
+#
+# Examples:
+#
+#   NEW_RESPONSE_REMINDER_AFTER_DAYS: [3, 7]
+#
+# ---
 NEW_RESPONSE_REMINDER_AFTER_DAYS: [3, 10, 24]
 
-# For debugging memory problems.  If true, the app logs
-# the memory use increase of the Ruby process due to the
-# request (Linux only).  Since Ruby never returns memory to the OS, if the
-# existing process previously served a larger request, this won't
-# show any consumption for the later request.
+# For debugging memory problems. If true, Alaveteli logs the memory use
+# increase of the Ruby process due to the request (Linux only). Since Ruby
+# never returns memory to the OS, if the existing process previously served a
+# larger request, this won't show any consumption for the later request.
+#
+# DEBUG_RECORD_MEMORY - Boolean (default: false)
+#
+# ---
 DEBUG_RECORD_MEMORY: false
 
-# Currently we default to using pdftk to compress PDFs.  You can
-# optionally try Ghostscript, which should do a better job of
-# compression.  Some versions of pdftk are buggy with respect to
-# compression, in which case Alaveteli doesn't recompress the PDFs at
-# all and logs a warning message "Unable to compress PDF"; which would
-# be another reason to try this setting.
+# Currently we default to using pdftk to compress PDFs. You can optionally try
+# Ghostscript, which should do a better job of compression. Some versions of
+# pdftk are buggy with respect to compression, in which case Alaveteli doesn't
+# recompress the PDFs at all and logs a warning message "Unable to compress
+# PDF" — which would be another reason to try this setting.
+#
+# USE_GHOSTSCRIPT_COMPRESSION - Boolean (default: false)
+#
+# ---
 USE_GHOSTSCRIPT_COMPRESSION: true
 
-# mySociety's gazeteer service.  Shouldn't change.
+# Alateveli uses mySociety's gazeteer service to determine country from
+# incoming IP address (this lets us suggest an Alaveteli in the user's country
+# if one exists). You shouldn't normally need to change this.
+#
+# GAZE_URL - String (default: http://gaze.mysociety.org)
+#
+# Examples:
+#
+#   GAZE_URL: http://gaze.example.org
+#
+# ---
 GAZE_URL: http://gaze.mysociety.org
 
-# The email address to which non-bounce responses should be forwarded
+# The email address to which non-bounce responses to emails sent out by
+# Alaveteli should be forwarded
+#
+# FORWARD_NONBOUNCE_RESPONSES_TO - String (default: user-support@localhost)
+#
+# Examples:
+#
+#   FORWARD_NONBOUNCE_RESPONSES_TO: user-support@example.com
+#
+# ---
 FORWARD_NONBOUNCE_RESPONSES_TO: user-support@localhost
 
-# Path to a program that converts an HTML page in a file to PDF.  It
-#should take two arguments: the URL, and a path to an output file.
+# Path to a program that converts an HTML page in a file to PDF. Also used to
+# download a zip file of all the correspondence for a request. It should take
+# two arguments: the URL, and a path to an output file.
+#
 # A static binary of wkhtmltopdf is recommended:
 # http://code.google.com/p/wkhtmltopdf/downloads/list
 # If the command is not present, a text-only version will be rendered
 # instead.
+#
+# HTML_TO_PDF_COMMAND - String (default: nil)
+#
+# Examples:
+#
+#   HTML_TO_PDF_COMMAND: /usr/local/bin/wkhtmltopdf
+#   HTML_TO_PDF_COMMAND: /usr/local/bin/wkhtmltopdf-amd64
+#
+# ---
 HTML_TO_PDF_COMMAND: /usr/local/bin/wkhtmltopdf-amd64
 
-# Exception notifications
+# Email address used for sending exception notifications.
+#
+# EXCEPTION_NOTIFICATIONS_FROM - String (default: nil)
+#
+# Examples:
+#
+#   EXCEPTION_NOTIFICATIONS_FROM: do-not-reply-to-this-address@example.com
+#
+# ---
 EXCEPTION_NOTIFICATIONS_FROM: do-not-reply-to-this-address@example.com
+
+# Email address(es) used for receiving exception notifications.
+#
+# EXCEPTION_NOTIFICATIONS_TO - Array of Strings (default: nil)
+#
+# Examples:
+#
+#   EXCEPTION_NOTIFICATIONS_TO:
+#     - robin@example.com
+#     - seb@example.com
+#
+# ---
 EXCEPTION_NOTIFICATIONS_TO:
- - robin@example.org
- - seb@example.org
+  - robin@example.org
+  - seb@example.org
 
 # This rate limiting can be turned off per-user via the admin interface
+#
+# MAX_REQUESTS_PER_USER_PER_DAY - Integer (default: nil)
+#
+# ---
 MAX_REQUESTS_PER_USER_PER_DAY: 6
 
+# If you're running behind Varnish set this to work out where to send purge
+# requests. Otherwise, don't set it.
+#
+# VARNISH_HOST - String (default: nil)
+#
+# Examples:
+#
+#   VARNISH_HOST: localhost
+#
+# ---
+# VARNISH_HOST: localhost
 
-# This is used to work out where to send purge requests.  Should be
-# unset if you aren't running behind varnish
-VARNISH_HOST: localhost
-
-# Adding a value here will enable Google Analytics on all non-admin pages for non-admin users.
+# Adding a value here will enable Google Analytics on all non-admin pages for
+# non-admin users.
+#
+# GA_CODE - String (default: nil)
+#
+# Examples:
+#
+#   GA_CODE: 'AB-8222142-14'
+#
+# ---
 GA_CODE: ''
 
-# If you want to override *all* the public body request emails with your own
-# email so that request emails that would normally go to the public body
-# go to you, then uncomment below and fill in your email.
-# Useful for a staging server to play with the whole process of sending requests
-# without inadvertently sending an email to a real authority
-#OVERRIDE_ALL_PUBLIC_BODY_REQUEST_EMAILS: test-email@foo.com
+# If you want to override all the public body request emails with your own
+# email address so that request emails that would normally go to the public
+# body go to you, use this setting. This is useful for a staging server, so you
+# can play with the whole process of sending requests without inadvertently
+# sending an email to a real authority.
+#
+# OVERRIDE_ALL_PUBLIC_BODY_REQUEST_EMAILS - String (default: nil)
+#
+# Examples:
+#
+#   OVERRIDE_ALL_PUBLIC_BODY_REQUEST_EMAILS: test-email@example.com
+#
+# ---
+# OVERRIDE_ALL_PUBLIC_BODY_REQUEST_EMAILS: test-email@example.com
 
-# Search path for external commandline utilities (such as pdftohtml, pdftk, unrtf)
+# Search path for external commandline utilities (such as pdftohtml, pdftk,
+# unrtf)
+#
+# UTILITY_SEARCH_PATH - Array of Strings
+#                       (default: ["/usr/bin", "/usr/local/bin"])
+#
+# Examples:
+#
+#  UTILITY_SEARCH_PATH: ["/usr/bin"]
+#  UTILITY_SEARCH_PATH: ["/usr/local/bin", "/opt/bin"]
+#
+# ---
 UTILITY_SEARCH_PATH: ["/usr/bin", "/usr/local/bin"]
 
-# Path to your exim or postfix log files that will get sucked up by script/load-mail-server-logs
+# Path to your exim or postfix log files that will get sucked up by
+# script/load-mail-server-logs
+#
+# MTA_LOG_PATH - String
+#
+# Examples:
+#
+#   MTA_LOG_PATH: '/var/log/exim4/exim-mainlog-*'
+#
+# ---
 MTA_LOG_PATH: '/var/log/exim4/exim-mainlog-*'
 
-# Whether we are using "exim" or "postfix" for our MTA
-MTA_LOG_TYPE: "exim"
+# Are you using "exim" or "postfix" for your Mail Transfer Agent (MTA)?
+#
+# MTA_LOG_TYPE - String (default: exim)
+#
+# Examples:
+#
+#   MTA_LOG_TYPE: exim
+#   MTA_LOG_TYPE: postfix
+#
+# ---
+MTA_LOG_TYPE: exim
 
 # URL where people can donate to the organisation running the site. If set,
 # this will be included in the message people see when their request is
 # successful.
+#
+# DONATION_URL - String (default: nil)
+#
+# Examples:
+#
+#   DONATION_URL: http://www.mysociety.org/donate
+#
+# ---
 DONATION_URL: "http://www.mysociety.org/donate/"
 
-# If you set this to 'true' then a page of statistics on the
-# performance of public bodies will be available:
+# If PUBLIC_BODY_STATISTICS_PAGE is set to true, Alaveteli will make a page of
+# statistics on the performance of public bodies (which you can see at
+# /body_statistics).
+#
+# PUBLIC_BODY_STATISTICS_PAGE - Boolean (default: false)
+#
+# ---
 PUBLIC_BODY_STATISTICS_PAGE: false
 
 # The page of statistics for public bodies will only consider public
-# bodies that have had at least this number of requests:
+# bodies that have had at least the number of requests set by
+# MINIMUM_REQUESTS_FOR_STATISTICS.
+#
+# MINIMUM_REQUESTS_FOR_STATISTICS - Integer (default: 100)
+#
+# ---
 MINIMUM_REQUESTS_FOR_STATISTICS: 50
 
-# If only some of the public bodies have been translated into every
-# available locale, you can allow a fallback to the default locale for
-# listing of public bodies.
+# If you would like the public body list page to include bodies that have no
+# translation in the current locale (but which do have a translation in the
+# default locale), set this to true.
+#
+# PUBLIC_BODY_LIST_FALLBACK_TO_DEFAULT_LOCALE - Boolean (default: false)
+#
+# ---
 PUBLIC_BODY_LIST_FALLBACK_TO_DEFAULT_LOCALE: false
 
 # If true, while in development mode, try to send mail by SMTP to port
-# 1025 (the port the mailcatcher listens on by default):
+# 1025 (the port the mailcatcher listens on by default)
+#
+# USE_MAILCATCHER_IN_DEVELOPMENT - Boolean (default: true)
+#
+# ---
 USE_MAILCATCHER_IN_DEVELOPMENT: true
 
-# Use memcached to cache HTML fragments for better performance. Will
+# Use memcached to cache HTML fragments for better performance. This will
 # only have an effect in environments where
 # config.action_controller.perform_caching is set to true
+#
+# CACHE_FRAGMENTS - Boolean (default: true)
+#
+# ---
 CACHE_FRAGMENTS: true
 
-# The default bundle path is vendor/bundle; you can set this option to
-# change it.
+# The default bundle path is vendor/bundle; you can set this option to change it
+#
+# BUNDLE_PATH - String
+#
+# Examples:
+#
+#   BUNDLE_PATH: vendor/bundle
+#   BUNDLE_PATH: /var/alaveteli/bundle
+#
+# ---
 BUNDLE_PATH: vendor/bundle
 
 # In some deployments of Alaveteli you may wish to install each newly
 # deployed version alongside the previous ones, in which case certain
-# files and resources should be shared between these installations:
-# for example, the 'files' directory, the 'cache' directory and the
+# files and resources should be shared between these installations.
+# For example, the 'files' directory, the 'cache' directory and the
 # generated graphs such as 'public/foi-live-creation.png'.  If you're
 # installing Alaveteli in such a setup then set SHARED_FILES_PATH to
-# the directory you're keeping these files under.  Otherwise, leave it
+# the directory you're keeping these files under. Otherwise, leave it
 # blank.
+#
+# SHARED_FILES_PATH - String
+#
+# Examples:
+#
+#   SHARED_FILES_PATH: /var/www/alaveteli/shared
+#
+# ---
 SHARED_FILES_PATH: ''
 
 # If you have SHARED_FILES_PATH set, then these options list the files
-# and directories that are shared; i.e. those that the deploy scripts
-# should create symlinks to from the repository.
+# that are shared; i.e. those that the deploy scripts should create symlinks to
+# from the repository.
+#
+# SHARED_FILES - Array of Strings
+#
+# Examples:
+#
+#   SHARED_FILES:
+#     - config/database.yml
+#     - config/general.yml
+#
+# ---
 SHARED_FILES:
- - config/database.yml
- - config/general.yml
- - config/rails_env.rb
- - config/newrelic.yml
- - config/httpd.conf
- - public/foi-live-creation.png
- - public/foi-user-use.png
- - config/aliases
+  - config/database.yml
+  - config/general.yml
+  - config/rails_env.rb
+  - config/newrelic.yml
+  - config/httpd.conf
+  - public/foi-live-creation.png
+  - public/foi-user-use.png
+  - config/aliases
+
+# If you have SHARED_FILES_PATH set, then these options list the directories
+# that are shared; i.e. those that the deploy scripts should create symlinks to
+# from the repository.
+#
+# SHARED_DIRECTORIES - Array of Strings
+#
+# Examples:
+#
+#   SHARED_DIRECTORIES:
+#     - files/
+#     - cache/
+#
+# ---
 SHARED_DIRECTORIES:
- - files/
- - cache/
- - lib/acts_as_xapian/xapiandbs/
- - log/
- - tmp/pids
- - vendor/bundle
- - public/assets
+  - files/
+  - cache/
+  - lib/acts_as_xapian/xapiandbs/
+  - log/
+  - tmp/pids
+  - vendor/bundle
+  - public/assets
 
 # Allow some users to make batch requests to multiple authorities. Once
 # this is set to true, you can enable batch requests for an individual
 # user via the user admin page.
-
+#
+# ALLOW_BATCH_REQUESTS - Boolean (default: false)
+#
+# ---
 ALLOW_BATCH_REQUESTS: false
 
-# Should we use the responsive stylesheets?
+# Use the responsive base stylesheets and templates, rather than those that
+# only render the site at a fixed width. These stylesheets are currently
+# experimental but will become the default in the future. They allow the site
+# to render nicely on mobile devices as well as larger screens. Currently the
+# fixed width stylesheets are used by default.
+#
+# RESPONSIVE_STYLING - Boolean (default: false)
+#
+# ---
 RESPONSIVE_STYLING: true