Logging documentation should describe how to configure logging handlers.

[ShawnMilo]

The logging documentation [1] is incomplete and confusing to users unfamiliar with the logging module's dictionary configs, and Python's own docs are pretty poor on this so they don't take up the slack.

Specifically, I think our docs should explain how to specify the filename used by a handler that writes to a file, by adding the 'filename' key to the dictionary, and elaborate by saying that any kwarg accepted by any handler type's init may be used here.

This tripped me up, and I just saw the same question asked on django-users by someone trying to figure out how to configure a SysLogHandler.

[1] ​https://docs.djangoproject.com/en/1.3/topics/logging/

[Aymeric Augustin]

Everything is described in [1] which is linked at the very beginning of [2].

[1] ​http://docs.python.org/library/logging.config.html#configuration-dictionary-schema

[2] ​https://docs.djangoproject.com/en/1.3/topics/logging/#configuring-logging

Excerpt:

All other keys are passed through as keyword arguments to the handler’s constructor.

That sounds clear and straightforward. There's even an example with a 'filename' just below. So I don't really understand why you find that the docs are poor or that this information is difficult to find.

The logging documentation may be intimidating, but:

• I really believe that this information belongs to Python's docs, and that it's not a good idea to start duplicating information in Django's docs;
• There are already exactly the proper links in Django's docs;
• Django developers are expected to be able to read 10 lines from the Python docs.

So I'm rather strongly -1.

[Aymeric Augustin]

Since nobody disagreed with my first comment after I asked on IRC, I am going to reject the ticket. Basically I don't see how we could improve the docs with regard to the points you raised.