classification
Title: Add link to source code in logging documentation
Type: enhancement Stage: resolved
Components: Documentation, Library (Lib) Versions:
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Johz, docs@python, python-dev, vinay.sajip
Priority: normal Keywords:

Created on 2013-09-05 14:10 by Johz, last changed 2013-09-05 22:02 by python-dev. This issue is now closed.

Messages (4)
msg197000 - (view) Author: Jonathan Frere (Johz) Date: 2013-09-05 14:10
The logging module documentation is probably best accompanied by the source that it is meant to be documenting.  Could a link to either the package directory (http://hg.python.org/cpython/file/2.7/Lib/logging/) or the __init__.py file in that directory (http://hg.python.org/cpython/file/2.7/Lib/logging/__init__.py), I'd argue the __init__.py file.
msg197005 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2013-09-05 15:01
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.
msg197011 - (view) Author: Jonathan Frere (Johz) Date: 2013-09-05 16:44
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.
msg197031 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-09-05 22:02
New changeset dc4e6b48c321 by Vinay Sajip in branch '2.7':
Issue #18933: Added links to source code.
http://hg.python.org/cpython/rev/dc4e6b48c321

New changeset 34e515f2fdfe by Vinay Sajip in branch '3.3':
Issue #18933: Added links to source code.
http://hg.python.org/cpython/rev/34e515f2fdfe

New changeset c5924523747e by Vinay Sajip in branch 'default':
Closes #18933: Merged update from 3.3.
http://hg.python.org/cpython/rev/c5924523747e
History
Date User Action Args
2013-09-05 22:02:58python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg197031

resolution: fixed
stage: resolved
2013-09-05 16:44:41Johzsetmessages: + msg197011
2013-09-05 15:01:34vinay.sajipsetmessages: + msg197005
2013-09-05 14:10:06Johzcreate