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

@@ -24,6 +24,11 @@
 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

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):

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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~