Move debugger details into a new section, #343.

docs/errorhandling.rst

@@ -1,7 +1,7 @@
 .. _application-errors:
 
-Handling Application Errors
+Logging Application Errors
-===========================
+==========================
 
 .. versionadded:: 0.3
 
@@ -235,3 +235,68 @@ iterating over them to attach handlers::
     for logger in loggers:
         logger.addHandler(mail_handler)
         logger.addHandler(file_handler)
+
+
+Debugging Application Errors
+============================
+
+For production applications, configure your application with logging and
+notifications as described in :ref:`application-errors`.  This section provides
+pointers when debugging deployment configuration and digging deeper with a
+full-featured Python debugger.
+
+
+When in Doubt, Run Manually
+---------------------------
+
+Having problems getting your application configured for production?  If you
+have shell access to your host, verify that you can run your application
+manually from the shell in the deployment environment.  Be sure to run under
+the same user account as the configured deployment to troubleshoot permission
+issues.  You can use Flask's builtin development server with `debug=True` on
+your production host, which is helpful in catching configuration issues, but
+**be sure to do this temporarily in a controlled environment.** Do not run in
+production with `debug=True`.
+
+
+.. _working-with-debuggers:
+
+Working with Debuggers
+----------------------
+
+To dig deeper, possibly to trace code execution, Flask provides a debugger out
+of the box (see :ref:`debug-mode`).  If you would like to use another Python
+debugger, note that debuggers interfere with each other.  You have to set some
+options in order to use your favorite debugger:
+
+* ``debug``        - whether to enable debug mode and catch exceptinos
+* ``use_debugger`` - whether to use the internal Flask debugger
+* ``use_reloader`` - whether to reload and fork the process on exception
+
+``debug`` must be True (i.e., exceptions must be caught) in order for the other
+two options to have any value.
+
+If you're using Aptana/Eclipse for debugging you'll need to set both
+``use_debugger`` and ``use_reloader`` to False.
+
+A possible useful pattern for configuration is to set the following in your
+config.yaml (change the block as approriate for your application, of course)::
+
+   FLASK:
+       DEBUG: True
+       DEBUG_WITH_APTANA: True
+
+Then in your application's entry-point (main.py), you could have something like::
+
+   if __name__ == "__main__":
+       # To allow aptana to receive errors, set use_debugger=False
+       app = create_app(config="config.yaml")
+
+       if app.debug: use_debugger = True
+       try:
+           # Disable Flask's debugger if external debugger is requested
+           use_debugger = not(app.config.get('DEBUG_WITH_APTANA'))
+       except:
+           pass
+       app.run(use_debugger=use_debugger, debug=app.debug,
+               use_reloader=use_debugger, host='0.0.0.0')

docs/quickstart.rst

@@ -77,6 +77,8 @@ To stop the server, hit control-C.
    This tells your operating system to listen on all public IPs.
 
 
+.. _debug-mode:
+
 Debug Mode
 ----------
 
@@ -112,42 +114,7 @@ Screenshot of the debugger in action:
    :class: screenshot
    :alt: screenshot of debugger in action
 
-.. admonition:: Working With Other Debuggers
+Have another debugger in mind? See :ref:`working-with-debuggers`.
-
-   Debuggers interfere with each other.
-   That said, you may still wish to use the debugger in a tool of your choice.
-   Flask provides the following options to manage the debug process:
-
-   * ``debug``        - whether to enable debug mode and catch exceptinos
-   * ``use_debugger`` - whether to use the internal Flask debugger
-   * ``use_reloader`` - whether to reload and fork the process on exception
-
-   ``debug`` must be True (i.e., exceptions must be caught) in order for the
-   other two options to have any value.
-
-   If you're using Aptana/Eclipse for debugging you'll need to set both
-   ``use_debugger`` and ``use_reloader`` to False.
-
-   A possible useful pattern for configuration is to set the following in your
-   config.yaml (change the block as approriate for your application, of course)::
-
-       FLASK:
-           DEBUG: True
-           DEBUG_WITH_APTANA: True
-
-   Then in your application's entry-point (main.py), you could have something like::
-
-       if __name__ == "__main__":
-           # To allow aptana to receive errors, set use_debugger=False
-           app = create_app(config="config.yaml")
-
-           if app.debug: use_debugger = True
-           try:
-               # Disable Flask's debugger if external debugger is requested
-               use_debugger = not(app.config.get('DEBUG_WITH_APTANA'))
-           except:
-               pass
-           app.run(use_debugger=use_debugger, debug=app.debug, use_reloader=use_debugger, host='0.0.0.0')
 
 
 Routing