Issue 18933: Add link to source code in logging documentation (original) (raw)

Why for the logging module in particular? This isn't the norm for stdlib packages, AFAIK.

The logging documentation (both tutorial and reference) is supposed to stand on its own, and in general I don't expect documentation users to (have to) look at the source to understand how to use logging.

If you think particular aspects of the documentation need clarifying, then please indicate what they are and suggest what sort of improvements you think are in order.

Well, if all the modules could link back to source code, that would be ideal, it's just the logging happens to be the one that I keep coming back to. Encouraging users to read the source will hopefully help people understand the modules they're using conceptually, and also give people more sample code to use.

That said, a number of modules link back to the source, particularly small single-file implementations of things, such as glob, fnmatch, string, pprint, repr, types, UserDict, weakref, Queue, sched, to name a few that I randomly opened.

Why logging in particular? Well, as I said, I keep on coming back to it, so at least one Python user feels this need. Secondly, it's a module that perhaps isn't quite as conceptually clear as others (hence the 'alternatives' that abound). Thirdly, parts of the module such as logging.handlers will be directly used as templates by many developers.