Monday 11 April 2011

Logging documentation for Python 2.7 reorganised

The logging documentation for Python 2.7 has been reorganised into the same structure as that for Python 3.x. The library reference is supposed to be just that – a reference – so the tutorials have been moved to the HOWTO section. The configuration and handler documentation has also been moved into separate pages. The organisation is now as follows:

There’s a prominent sidebar at the start of the reference documentation pages pointing to the HOWTO sections.

I hope the results are easier to navigate and to understand. Please feel free to give your feedback.

4 comments:

  1. I actually found the now-removed "Basic example" more gentle than its replacement: http://docs.python.org/release/2.6.6/library/logging#basic-example. It has a smooth step-by-step demo of simple usgae of basicConfig().

    ReplyDelete
  2. Thanks for the feedback. The "Basic example" from the 2.6 documentation contains all of the following items in a single section: logging to console, logging to file, logging variable data and formatting of messages. In the HOWTO, this has been split into sections, so that perhaps it seems more disjointed/not as smooth. However, the sidebar does allow you to jump to each of the relevant subsections (e.g. "Logging to a file") quite easily.

    ReplyDelete
  3. Well done, this chapter was indeed in need of a major overall and your effort is very much appreciated.

    I agree with Vinay though, I think the first basic example should directly show how to change the level to INFO and change the format to remove the logger name (which is what people want to do in 90% of the case in simple scripts with the default root logger).

    Ideally, this basic example should be displayed on the top of the page (without having to scroll down), without any explanation (the detailed explanations you give afterwards in the following sections are good).

    ReplyDelete
  4. Do you mean that you agree with Tshepang, rather than with me?

    If you look at the basic example section:

    http://docs.python.org/howto/logging#a-simple-example

    then you see two examples in the page, including an example of changing the level. The reason why this is not the very first thing on the page is because of the preceding "When to use logging" section. This section contains useful advice about logging, and seems the best place to have it (as someone, on reading it, may realise that what they really want to do is to use the warnings module instead, or just a plain print call). Also described there are the levels and what they signify, which is pertinent to the stuff which follows.

    ReplyDelete