rewrite debugging docs, move to separate page

docs/blueprints.rst

@@ -242,7 +242,6 @@ you can use relative redirects by prefixing the endpoint with a dot only::
 This will link to ``admin.index`` for instance in case the current request
 was dispatched to any other admin blueprint endpoint.
 
-.. _my-blueprint-error-label:
 
 Blueprint Error Handlers
 ------------------------

docs/debugging.rst

@@ -0,0 +1,97 @@
+Debugging Application Errors
+============================
+
+
+In Production
+-------------
+
+**Do not run the development server, or enable the built-in debugger, in
+a production environment.** The debugger allows executing arbitrary
+Python code from the browser. It's protected by a pin, but that should
+not be relied on for security.
+
+Use an error logging tool, such as Sentry, as described in
+:ref:`error-logging-tools`, or enable logging and notifications as
+described in :doc:`/logging`.
+
+If you have access to the server, you could add some code to start an
+external debugger if ``request.remote_addr`` matches your IP. Some IDE
+debuggers also have a remote mode so breakpoints on the server can be
+interacted with locally. Only enable a debugger temporarily.
+
+
+The Built-In Debugger
+---------------------
+
+The built-in Werkzeug development server provides a debugger which shows
+an interactive traceback in the browser when an unhandled error occurs
+during a request. This debugger should only be used during development.
+
+.. image:: _static/debugger.png
+   :align: center
+   :class: screenshot
+   :alt: screenshot of debugger in action
+
+.. warning::
+
+    The debugger allows executing arbitrary Python code from the
+    browser. It is protected by a pin, but still represents a major
+    security risk. Do not run the development server or debugger in a
+    production environment.
+
+To enable the debugger, run the development server with the
+``FLASK_ENV`` environment variable set to ``development``. This puts
+Flask in debug mode, which changes how it handles some errors, and
+enables the debugger and reloader.
+
+.. code-block:: text
+
+    $ export FLASK_ENV=development
+    $ flask run
+
+``FLASK_ENV`` can only be set as an environment variable. When running
+from Python code, passing ``debug=True`` enables debug mode, which is
+mostly equivalent. Debug mode can be controled separately from
+``FLASK_ENV`` with the ``FLASK_DEBUG`` environment variable as well.
+
+.. code-block:: python
+
+    app.run(debug=True)
+
+:doc:`/server` and :doc:`/cli` have more information about running the
+debugger, debug mode, and development mode. More information about the
+debugger can be found in the `Werkzeug documentation
+<https://werkzeug.palletsprojects.com/debug/>`__.
+
+
+External Debuggers
+------------------
+
+External debuggers, such as those provided by IDEs, can offer a more
+powerful debugging experience than the built-in debugger. They can also
+be used to step through code during a request before an error is raised,
+or if no error is raised. Some even have a remote mode so you can debug
+code running on another machine.
+
+When using an external debugger, the app should still be in debug mode,
+but it can be useful to disable the built-in debugger and reloader,
+which can interfere.
+
+When running from the command line:
+
+.. code-block:: text
+
+    $ export FLASK_ENV=development
+    $ flask run --no-debugger --no-reload
+
+When running from Python:
+
+.. code-block:: python
+
+    app.run(debug=True, use_debugger=False, use_reloader=False)
+
+Disabling these isn't required, an external debugger will continue to
+work with the following caveats. If the built-in debugger is not
+disabled, it will catch unhandled exceptions before the external
+debugger can. If the reloader is not disabled, it could cause an
+unexpected reload if code changes during debugging.

docs/errorhandling.rst

@@ -73,8 +73,6 @@ See also:
 -   `Flask-specific documentation <https://docs.sentry.io/platforms/python/flask/>`__
 
 
-.. _error-handlers:
-
 Error Handlers
 --------------
 
@@ -529,63 +527,12 @@ parameter.
 Logging
 -------
 
-See :doc:`/logging` for information on how to log exceptions, such as by
+See :doc:`/logging` for information about how to log exceptions, such as
-emailing them to admins.
+by emailing them to admins.
-
-Debugging Application Errors
-============================
-
-For production applications, configure your application with logging and
-notifications as described in :doc:`/logging`. 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:
+Debugging
+---------
 
-Working with Debuggers
+See :doc:`/debugging` for information about how to debug errors in
-----------------------
+development and production.
-
-The built-in development server provides a :ref:`debug-mode` that shows
-an interactive traceback in the browser when an unhandled error occurs
-during a request.
-
-External debuggers, such as those provided by IDEs, can offer a much
-more powerful and visual debugging experience. They can also be used to
-step through code during a request before an error is raised, or if no
-error is raised.
-
-When using an external debugger, the app should still be in debug mode,
-but it can be useful to disable the built-in debugger and reloader,
-which can interfere.
-
-When running from the command line:
-
-.. code-block:: text
-
-    $ export FLASK_ENV=development
-    $ flask run --no-debugger --no-reload
-
-When running from Python:
-
-.. code-block:: python
-
-    app.run(debug=True, use_debugger=False, use_reloader=False)
-
-Disabling these isn't required, an external debugger will continue to
-work with the following caveats. If the built-in debugger is not
-disabled, it will catch unhandled exceptions before the external
-debugger can. If the reloader is not disabled, it could cause an
-unexpected reload if code changes during debugging.

docs/index.rst

@@ -44,6 +44,7 @@ instructions for web development with Flask.
    templating
    testing
    errorhandling
+   debugging
    logging
    config
    signals

docs/quickstart.rst

@@ -111,59 +111,43 @@ application). It will tell you what it tried to import and why it failed.
 The most common reason is a typo or because you did not actually create an
 ``app`` object.
 
-.. _debug-mode:
 
 Debug Mode
 ----------
 
-(Want to just log errors and stack traces? See :doc:`errorhandling`)
+The ``flask run`` command can do more than just start the development
+server. By enabling debug mode, the server will automatically reload if
+code changes, and will show an interactive debugger in the browser if an
+error occurs during a request.
 
-The :command:`flask` script is nice to start a local development server, but
+.. image:: _static/debugger.png
-you would have to restart it manually after each change to your code.
+    :align: center
-That is not very nice and Flask can do better.  If you enable debug
+    :class: screenshot
-support the server will reload itself on code changes, and it will also
+    :alt: The interactive debugger in action.
-provide you with a helpful debugger if things go wrong.
 
-To enable all development features (including debug mode) you can export
+.. warning::
-the ``FLASK_ENV`` environment variable and set it to ``development``
+
-before running the server::
+    The debugger allows executing arbitrary Python code from the
+    browser. It is protected by a pin, but still represents a major
+    security risk. Do not run the development server or debugger in a
+    production environment.
+
+To enable all development features, set the ``FLASK_ENV`` environment
+variable to ``development`` before calling ``flask run``.
+
+.. code-block:: text
 
     $ export FLASK_ENV=development
     $ flask run
 
-(On Windows you need to use ``set`` instead of ``export``.)
+See also:
 
-This does the following things:
+-   :doc:`/server` and :doc:`/cli` for information about running in
-
+    development mode.
-1.  it activates the debugger
+-   :doc:`/debugging` for information about using the built-in debugger
-2.  it activates the automatic reloader
+    and other debuggers.
-3.  it enables the debug mode on the Flask application.
+-   :doc:`/logging` and :doc:`/errorhandling` to log errors and display
-
+    nice error pages.
-You can also control debug mode separately from the environment by
-exporting ``FLASK_DEBUG=1``.
-
-There are more parameters that are explained in :doc:`/server`.
-
-.. admonition:: Attention
-
-   Even though the interactive debugger does not work in forking environments
-   (which makes it nearly impossible to use on production servers), it still
-   allows the execution of arbitrary code. This makes it a major security risk
-   and therefore it **must never be used on production machines**.
-
-Screenshot of the debugger in action:
-
-.. image:: _static/debugger.png
-   :align: center
-   :class: screenshot
-   :alt: screenshot of debugger in action
-
-More information on using the debugger can be found in the `Werkzeug
-documentation`_.
-
-.. _Werkzeug documentation: https://werkzeug.palletsprojects.com/debug/#using-the-debugger
-
-Have another debugger in mind? See :ref:`working-with-debuggers`.
 
 
 HTML Escaping