Document all available application settings.

bdarnell · bdarnell · commit 790d86a469e6 · 2012-08-27T18:56:34.000-04:00
diff --git a/tornado/web.py b/tornado/web.py
@@ -629,6 +629,13 @@ def get_template_namespace(self):
         return namespace
 
     def create_template_loader(self, template_path):
+        """Returns a new template loader for the given path.
+
+        May be overridden by subclasses.  By default returns a
+        directory-based loader on the given path, using the
+        ``autoescape`` application setting.  If a ``template_loader``
+        application setting is supplied, uses that instead.
+        """
         settings = self.application.settings
         if "template_loader" in settings:
             return settings["template_loader"]
@@ -1219,18 +1226,6 @@ class Application(object):
     and we will serve /favicon.ico and /robots.txt from the same directory.
     A custom subclass of StaticFileHandler can be specified with the
     static_handler_class setting.
-
-    .. attribute:: settings
-
-       Additional keyword arguments passed to the constructor are saved in the
-       `settings` dictionary, and are often referred to in documentation as
-       "application settings".
-
-    .. attribute:: debug
-
-       If `True` the application runs in debug mode, described in
-       :ref:`debug-mode`. This is an application setting in the `settings`
-       dictionary, so handlers can access it.
     """
     def __init__(self, handlers=None, default_host="", transforms=None,
                  wsgi=False, **settings):
diff --git a/website/sphinx/overview.rst b/website/sphinx/overview.rst
@@ -486,6 +486,8 @@ for more details. Check out the `Tornado Blog example application <https://githu
 complete example that uses authentication (and stores user data in a
 MySQL database).
 
+.. _xsrf:
+
 Cross-site request forgery protection
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -749,6 +751,8 @@ See the `tornado.locale`
 documentation for detailed information on the CSV format and other
 localization methods.
 
+.. _ui-modules:
+
 UI modules
 ~~~~~~~~~~
 
diff --git a/website/sphinx/web.rst b/website/sphinx/web.rst
@@ -77,6 +77,7 @@
    .. automethod:: RequestHandler.async_callback
    .. automethod:: RequestHandler.check_xsrf_cookie
    .. automethod:: RequestHandler.compute_etag
+   .. automethod:: RequestHandler.create_template_loader
    .. automethod:: RequestHandler.get_browser_locale
    .. automethod:: RequestHandler.get_current_user
    .. automethod:: RequestHandler.get_login_url
@@ -97,6 +98,76 @@
    .. autoclass:: Application
       :members:
 
+      .. attribute:: settings
+
+         Additional keyword arguments passed to the constructor are
+         saved in the `settings` dictionary, and are often referred to
+         in documentation as "application settings".  Settings are
+         used to customize various aspects of Tornado (although in
+         some cases richer customization is possible by overriding
+         methods in a subclass of `RequestHandler`).  Some
+         applications also like to use the `settings` dictionary as a
+         way to make application-specific settings available to
+         handlers without using global variables.  Settings used in
+         Tornado are described below.
+
+         General settings:
+
+         * ``debug``: If ``True`` the application runs in debug mode,
+           described in :ref:`debug-mode`.
+         * ``gzip``: If ``True``, responses in textual formats will be
+           gzipped automatically.
+         * ``log_function``: This function will be called at the end
+           of every request to log the result (with one argument, the
+           `RequestHandler` object).  The default implementation
+           writes to the `logging` module's root logger.  May also be
+           customized by overriding `Application.log_request`.
+         * ``ui_modules`` and ``ui_methods``: May be set to a mapping
+           of `UIModule` or UI methods to be made available to templates.
+           May be set to a module, dictionary, or a list of modules
+           and/or dicts.  See :ref:`ui-modules` for more details.
+
+         Authentication and security settings:
+
+         * ``cookie_secret``: Used by `RequestHandler.get_secure_cookie`
+           and `set_secure_cookie` to sign cookies.
+         * ``login_url``: The `authenticated` decorator will redirect
+           to this url if the user is not logged in.  Can be further
+           customized by overriding `RequestHandler.get_login_url`
+         * ``xsrf_cookies``: If true, :ref:`xsrf` will be enabled.
+         * ``twitter_consumer_key``, ``twitter_consumer_secret``,
+           ``friendfeed_consumer_key``, ``friendfeed_consumer_secret``,
+           ``google_consumer_key``, ``google_consumer_secret``,
+           ``facebook_api_key``, ``facebook_secret``:  Used in the
+           `tornado.auth` module to authenticate to various APIs.
+
+         Template settings:
+
+         * ``autoescape``: Controls automatic escaping for templates.
+           May be set to ``None`` to disable escaping, or to the *name*
+           of a function that all output should be passed through.
+           Defaults to ``"xhtml_escape"``.  Can be changed on a per-template
+           basis with the ``{% autoescape %}`` directive.
+         * ``template_path``: Directory containing template files.  Can be
+           further customized by overriding `RequestHandler.get_template_path`
+         * ``template_loader``: Assign to an instance of
+           `tornado.template.BaseLoader` to customize template loading.
+           If this setting is used the ``template_path`` and ``autoescape``
+           settings are ignored.  Can be further customized by overriding
+           `RequestHandler.create_template_loader`.
+
+         Static file settings:
+
+         * ``static_path``: Directory from which static files will be
+           served.
+         * ``static_url_prefix``:  Url prefix for static files,
+           defaults to ``"/static/"``.
+         * ``static_handler_class``, ``static_handler_args``: May be set to
+           use a different handler for static files instead of the default
+           `tornado.web.StaticFileHandler`.  ``static_handler_args``, if set,
+           should be a dictionary of keyword arguments to be passed to the
+           handler's ``initialize`` method.
+
    .. autoclass:: URLSpec
 
       The ``URLSpec`` class is also available under the name ``tornado.web.url``.
