[Python-Dev] Using logging in the stdlib and its unit tests

[Nick Coghlan]

On Sun, Dec 12, 2010 at 5:32 AM, Brett Cannon <brett at python.org> wrote:
> On Fri, Dec 10, 2010 at 22:21, Vinay Sajip <vinay_sajip at yahoo.co.uk> wrote:
>> Nick Coghlan <ncoghlan <at> gmail.com> writes:
>>
>>
>>> This could actually make a reasonably good basic for a "task oriented"
>>> subsection of the logging documentation. Something like:
>>>
>>
>> Good suggestion, I'll see what I can do.
>
> Just wanted to +1 on some task-oriented (or at least simple intro)
> docs going into the logging module.

I think Vinay has made some great improvements to the logging module
docs in the last day or two. The latest version out of SVN is
available on the site at the usual location:
http://docs.python.org/dev/library/logging

I am putting some minor notes here for Vinay's benefit (I can put them
on the tracker instead, if he would prefer):

General
  It may be worth talking to Georg about how best to split the logging
docs up into multiple files. The sidebar menu is getting kinda
overwhelmed.

14.7.1.1
  Parenthetical comment in first row of second table should start with
"(e.g. for" not "(e.g. or"

14.7.1.8
  Probably best to say "that's it for the basic tutorial" and then
point people towards the advanced tutorial in 14.7.2 before setting
them loose on the rest of the docs. The advanced tutorial defines the
terminology and gives the necessary structure to help keep the
detailed docs in perspective without being overwhelmed by the detail.

14.7.2.1
  Something appears to have gone wrong with the first bulleted list.
It is missing the "These are the configuration methods:" intro text,
as well as a bullet for add/removeHandler
  The "does not address filters" part should cross-reference the
detailed section on filter objects
  This section should state explicitly whether or not the level
setting on a child logger affects which messages it passes to its
parent logger

14.7.2.5
  This section is out of date, and needs to be caveated to make it
clear that it applies only to version prior to Python 3.2 (for 3.2, it
can describe the new handler of last resort behaviour)

And that's the end of the two tutorials... very nice update :)

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia