Started the new documentation for logbook's integration

mitsuhiko · mitsuhiko · commit 24c8e8a098b2 · 2010-09-13T04:59:34.000+02:00
diff --git a/docs/attic/index.rst b/docs/attic/index.rst
@@ -0,0 +1,15 @@
+Old Documentation
+=================
+
+This part of the documentation contains documents that are no longer
+necessary in recent Flask versions because they document deprecated
+functionality or changed behaviour.  We keep it around for a certain
+period of time because it is still relevant if you relay on this
+deprecated functionality.
+
+You are however encouraged to upgrade your application to no longer
+depend on this behaviour.
+
+.. toctree::
+
+   logging
diff --git a/docs/attic/logging.rst b/docs/attic/logging.rst
@@ -1,10 +1,16 @@
-.. _application-errors:
+.. _old-logging:
 
-Handling Application Errors
-===========================
+Setting up the old Logging System
+=================================
 
 .. versionadded:: 0.3
 
+.. admonition:: Pending Deprecation
+
+   This document specifies soon to be deprecated functionality that will
+   be removed in Flask 1.0.  Please have a look at the new :ref:`logging`
+   documentation instead.
+
 Applications fail, servers fail.  Sooner or later you will see an exception
 in production.  Even if your code is 100% correct, you will still see
 exceptions from time to time.  Why?  Because everything else involved will
diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc
@@ -14,7 +14,7 @@ instructions for web development with Flask.
    tutorial/index
    templating
    testing
-   errorhandling
+   logging
    config
    signals
    shell
@@ -41,6 +41,7 @@ Design notes, legal information and changelog are here for the interested.
 .. toctree::
    :maxdepth: 2
 
+   attic/index
    design
    htmlfaq
    security
diff --git a/docs/logging.rst b/docs/logging.rst
@@ -0,0 +1,59 @@
+.. _logging:
+
+Logging and Errorhandling
+=========================
+
+.. versionadded:: 0.7
+
+Applications fail, servers fail.  Sooner or later you will see an exception
+in production.  Even if your code is 100% correct, you will still see
+exceptions from time to time.  Why?  Because everything else involved will
+fail.  Here some situations where perfectly fine code can lead to server
+errors:
+
+-   the client terminated the request early and the application was still
+    reading from the incoming data.
+-   the database server was overloaded and could not handle the query.
+-   a filesystem is full
+-   a harddrive crashed
+-   a backend server overloaded
+-   a programming error in a library you are using
+-   network connection of the server to another system failed.
+
+And that's just a small sample of issues you could be facing.  So how do we
+deal with that sort of problem?  By default if your application runs in
+production mode, Flask will display a very simple page for you and log the
+exception to the :attr:`~flask.Flask.logger`.
+
+But there is more you can do, and we will cover some better setups to deal
+with errors.
+
+The Logging System
+------------------
+
+In Flask 0.3 we started off with supporting a clever default configuration
+of the :mod:`logging` package that comes with Python.  In Flask 0.7 we are
+starting to make the switch to a new log system called `Logbook`_.
+
+The default will continue to be the logging module until we hit 1.0 when
+we change the default to Logbook.  Two versions after that we will remove
+the support for logging in general.
+
+Why are we doing that?  Unfortunately the logging library in Python was
+designed with a different kind of application setup in mind.  In web
+applications what happens is that a thread usually handles a request and
+whatever is happening in this thread until a certain point is considered
+"belonging" to the same request.  The Python logging library however does
+not support the idea of per-thread based configurations.  Instead it is
+using a global registry of loggers which does not translate well to an
+application setup.
+
+The way logbook works is that it keeps per-thread configurations of your
+logging system which gives you the ability to better customize the
+behaviour of the system and provides better means of debugging.
+
+This document only specifies a logbook setup.  If you are interested in
+the documentation for the old logging system, have a look at
+:ref:`old-logging`.
+
+.. _Logbook: http://logbook.pocoo.org/
diff --git a/docs/patterns/errorpages.rst b/docs/patterns/errorpages.rst
@@ -39,7 +39,7 @@ even if the application behaves correctly:
     Usually happens on programming errors or if the server is overloaded.
     A terrible good idea to have a nice page there, because your
     application *will* fail sooner or later (see also:
-    :ref:`application-errors`).
+    :ref:`old-logging`).
 
 
 Error Handlers
diff --git a/docs/upgrading.rst b/docs/upgrading.rst
@@ -125,7 +125,7 @@ If you run your application in production and want to profit from
 automatic error logging, you might be interested in attaching a proper log
 handler.  Also you can start logging warnings and errors into the logger
 when appropriately.  For more information on that, read
-:ref:`application-errors`.
+:ref:`old-logging`.
 
 Categories for Flash Messages
 `````````````````````````````
