Permalink
Browse files

Documentation updates

  • Loading branch information...
1 parent b27ab58 commit 6aff2299aaa81de99b7b7fe7f7ac32e1899e5836 @mitsuhiko mitsuhiko committed Sep 20, 2010
Showing with 41 additions and 11 deletions.
  1. +2 −0 docs/api/notifiers.rst
  2. +9 −5 docs/features.rst
  3. +11 −6 docs/index.rst
  4. +19 −0 docs/libraries.rst
View
@@ -1,3 +1,5 @@
+.. _notifiers:
+
The Notifiers Module
====================
View
@@ -1,10 +1,12 @@
-Why you should use Logbook
-==========================
+What does it do?
+================
Although the Python standard library provides a logging system, you should
consider having a look at Logbook for your applications. Currently
logbook is an alpha version and should be considered a developer preview.
+But give it a try, we think it will work out for you and be fun to use :)
+
Furthermore because it was prototyped in a couple of days, it leverages
some features of Python that are not available in older Python releases.
Logbook current requires Python 2.5 or higher and does not yet support
@@ -52,14 +54,16 @@ Core Features
levels are not supported, instead we strongly recommend using logging
subclasses or log processors that inject tagged information into the log
record for this purpose.
+- :pep:`8` naming and code style.
Advantages over Logging
-----------------------
If properly configured, Logbook's logging calls will be very cheap and
-provide a great performance improvement over the standard library's
-logging module. While we are not quite there yet, there will be some
-further performance improvements in the upcoming versions.
+provide a great performance improvement over an equivalent configuration
+of the standard library's logging module. While for some parts we are not
+quite at performance we desire, there will be some further performance
+improvements in the upcoming versions.
It also supports the ability to inject additional information for all
logging calls happening in a specific thread or for the whole application.
View
@@ -2,18 +2,23 @@ Welcome to Logbook
==================
Logbook is a logging sytem for Python that replaces the standard library's
-logging module. It was designed with complex and simple applications in mind.
+logging module. It was designed with both complex and simple applications
+and mind and the idea to make logging fun:
>>> from logbook import Logger
>>> log = Logger('Logbook')
>>> log.info('Hello, World!')
[2010-07-23 16:34] INFO: Logbook: Hello, World!
-This library is still under heavy development and the API is not fully finalized
-yet. Feedback is appreciated. The docs here only show a tiny, tiny feature set
-and are terribly incomplete. We will have better docs soon, but until then we
-hope this gives a sneak peak about how cool Logbook is. If you want more, have
-a look at the comprehensive `testsuite`_.
+What makes it fun? What about getting log messages on your phone or
+desktop notification system? :ref:`Logbook can do that <notifiers>`.
+
+This library is still under heavy development and the API is not fully
+finalized yet. Feedback is appreciated. The docs here only show a tiny,
+tiny feature set and are terribly incomplete. We will have better docs
+soon, but until then we hope this gives a sneak peak about how cool
+Logbook is. If you want more, have a look at the comprehensive
+`testsuite`_.
Documentation
-------------
View
@@ -51,3 +51,22 @@ Best Practices
handler for a call to a noisy function is fine, changing the global
stack in a function and not reverting it at the end of the function is
bad.
+
+Debug Loggers
+-------------
+
+Sometimes you want to have loggers in place that are only really good for
+debugging. For example you might have a library that does a lot of
+server/client communication and for debugging purposes it would be nice if
+you can enable/disable that log output as necessary.
+
+In that case it makes sense to create a logger and disable that by default
+and give people a way to get hold of the logger to flip the flag.
+Additionally you can override the :attr:`~logbook.Logger.disabled` flag to
+automatically set it based on another value::
+
+ class MyLogger(Logger):
+ @property
+ def disabled(self):
+ return not database_connection.debug
+ database_connection.logger = MyLogger('mylibrary.dbconnection')

0 comments on commit 6aff229

Please sign in to comment.