From 753bbbff623df71b00502d6095ff17c9643695ab Mon Sep 17 00:00:00 2001
From: Evan Jones <ej@evanjones.ca>
Date: Thu, 14 Jun 2012 15:34:42 -0400
Subject: [PATCH] Documentation: Application(debug=True); autoreload
 limitations.

Application: Document debug=True and cross-link to the overview.
autoreload: Note that this can lose flags and fail if you touch sys.argv.
---
 tornado/autoreload.py       | 5 +++++
 tornado/web.py              | 8 +++++++-
 website/sphinx/overview.rst | 8 ++++++++
 3 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/tornado/autoreload.py b/tornado/autoreload.py
index 286782c7..55a10d10 100644
--- a/tornado/autoreload.py
+++ b/tornado/autoreload.py
@@ -24,6 +24,11 @@ and static resources.
 This module depends on IOLoop, so it will not work in WSGI applications
 and Google AppEngine.  It also will not work correctly when HTTPServer's
 multi-process mode is used.
+
+Reloading loses any Python interpreter command-line arguments (e.g. ``-u``)
+because it re-executes Python using ``sys.executable`` and ``sys.argv``.
+Additionally, modifying these variables will cause reloading to behave
+incorrectly.
 """
 
 from __future__ import absolute_import, division, with_statement
diff --git a/tornado/web.py b/tornado/web.py
index a7c9637f..a9bc5046 100644
--- a/tornado/web.py
+++ b/tornado/web.py
@@ -1208,9 +1208,15 @@ class Application(object):
 
     .. attribute:: settings
 
-       Additonal keyword arguments passed to the constructor are saved in the
+       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
index 7ea7b68d..b27e7508 100644
--- a/website/sphinx/overview.rst
+++ b/website/sphinx/overview.rst
@@ -957,6 +957,8 @@ the Google credentials in a cookie for later access:
 
 See the `tornado.auth` module documentation for more details.
 
+.. _debug-mode:
+
 Debug mode and automatic reloading
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -976,6 +978,12 @@ The automatic reloading feature of debug mode is available as a
 standalone module in ``tornado.autoreload``, and is optionally used by
 the test runner in ``tornado.testing.main``.
 
+Reloading loses any Python interpreter command-line arguments (e.g. ``-u``)
+because it re-executes Python using ``sys.executable`` and ``sys.argv``.
+Additionally, modifying these variables will cause reloading to behave
+incorrectly.
+
+
 Running Tornado in production
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~