[Python-Dev] logging doc broken

[Vinay Sajip]

Nick Coghlan <ncoghlan <at> gmail.com> writes:

> Vinay is currently working on updates to the logging documentation,
> and this is one of the things that is likely to change (with the table
> of attributes moved to the LogRecord section and referenced from the
> sections on Formatter and Filter objects).

Yes, and to compound matters, the LogRecord constructor documentation lists the
attribute values in the place you'd expect the parameters to appear, using the
doc markup for attributes. This I think is what causes the confusion, although
the markup is different to that used for parameters it's not clear at first
glance.

However, these changes are after 2.7 and 3.1: In 2.6 documentation the
parameters are named as in the source, but there's no reference in the
LogRecord reference documentation about any attributes of the LogRecord.

Perhaps it would be best to do the following:

- Add constructor params using normal parameter markup (:param:)
- Create a separate section "LogRecord Attributes" with a table containing attr
name, description, how to use with % formatting and how to use with
{}-formatting. There is some overlap here with the parameter documentation for
the LogRecord constructor, but I can put in a rider which explains that the
param names and attr names are slightly different. (I could kick myself now for
not being more scrupulous originally, but I'm not sure I can go back and change
the param names in the source code now because in theory, someone might be
constructing a LogRecord using LogRecord(**kwargs)).

- Link to the latter section from the Formatter, Filter sections.

Anyone see problems with this, or have a better suggestion?

Regards,

Vinay Sajip