classification
Title: Provide links to the source code for every module in the documentation
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.5, Python 3.4, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: Julian, akuchling, docs@python, eric.araujo, ezio.melotti, python-dev, rhettinger, terry.reedy
Priority: normal Keywords:

Created on 2011-11-20 00:29 by Julian, last changed 2014-03-19 20:27 by akuchling. This issue is now closed.

Files
File name Uploaded Description Edit
13437-patch.txt akuchling, 2014-03-18 21:51 review
Messages (12)
msg147973 - (view) Author: Julian Berman (Julian) * Date: 2011-11-20 00:29
The documentation occasionally contains a link to the source code for a module in the stdlib. See for instance http://docs.python.org/library/urlparse.html and http://docs.python.org/library/collections.html , or many others.

With a quick perusal, I couldn't immediately guess as to which ones managed to have one and which ones don't, but it'd be convenient to have a link in as many places as possible, which is certainly more than we have now. (See e.g. http://docs.python.org/library/json.html and http://docs.python.org/library/itertools.html and many others for examples of pages that lack a link).

Perhaps putting it in a more conspicuous but still consistent location would be reasonable (the sidebar?).
msg147988 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-11-20 12:26
Hi Julian, thanks for your interest in improving Python and welcome!  It is Raymond who initially added these links, and I helped porting them between versions.  The criterion can be read in the commit message: “Provide links to Python source in a handful of cases where the source is a generally helpful adjunct to the docs” (from http://hg.python.org/cpython/rev/fdd3681b1439/).  Not all modules have source code that is easy or helpful to read; not all modules have Python source code (itertools doesn’t).  I think Raymond is not willing to add links for all modules, but if you have a list of specific names which would benefit from source links, I’m sure he will consider them.
msg148021 - (view) Author: Julian Berman (Julian) * Date: 2011-11-21 00:47
Here's first a quick list from one pass over the docs. I've attempted to limit myself to a few like you've suggested, though I'll wait for confirmation that Raymond is not willing to simply add them to everything once we're at it :).

http://docs.python.org/library/difflib.html
http://docs.python.org/library/stringio.html
http://docs.python.org/library/codecs.html
http://docs.python.org/library/stringprep.html
http://docs.python.org/library/datetime.html
http://docs.python.org/library/math.html
http://docs.python.org/library/cmath.html
http://docs.python.org/library/decimal.html
http://docs.python.org/library/itertools.html
http://docs.python.org/library/os.path.html
http://docs.python.org/library/csv.html
http://docs.python.org/library/configparser.html
http://docs.python.org/library/logging.html
http://docs.python.org/library/getpass.html
http://docs.python.org/library/json.html
http://docs.python.org/library/urllib2.html
http://docs.python.org/library/unittest.html
http://docs.python.org/library/code.html

When I hit the docs to diagnose a problem, it's usually to take a quick look, and then to hit the source code to read that too, since most of the stuff that's in general use is common enough for me to know how it works in a general sense, so the source code is typically where I go pretty quickly after reading what the docs have to say.

It's not a huge deal obviously, hg.python.com is not the furthest thing away. Just seems convenient, especially since like I said a lot of the other ones I peek at already have links.


As for non-python modules, I really would like to say that linking to C source sounds just as reasonable to me, a little C never killed anyone :), but I don't want to push my luck, so I'll stick with whatever I can get here I guess (I know I put some non-python modules on the list).
msg148033 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-11-21 12:06
There are usually two cases that lead me to check the code:
1) The documentation is incomplete, not clear, missing, or plain wrong;
2) I want to check how something is implemented, mostly just out of curiosity;

Regarding the first case, in theory the docs should be informative and correct enough to not require you to go and check the code.  If they aren't you can report issues and we can improve it.
The second case applies to pretty much any module.  Linking to the code might also expose some internal details that should be just ignored by the user.  The code in some modules is also pretty old and might be a "bad" example (because it doesn't use modern conventions).
Some of the modules you listed are actually packages, so that would require to link to several files.
msg148432 - (view) Author: Julian Berman (Julian) * Date: 2011-11-27 00:21
Well, if there's opposition I don't know how strongly I feel about this then, but I generally agree with you Ezio, if there's an occasion where 1) applies fixing the docs is certainly reasonable. If I'm checking the source though, it's not necessarily since the documentation is unclear, just that it's often easier to read code than English.

But, I guess if no one else feels it'd be helpful feel free to close this then.
msg214030 - (view) Author: A.M. Kuchling (akuchling) * (Python committer) Date: 2014-03-18 21:51
Here's a patch for some of Julian's suggested modules.  I went through Julian's list and included code links for the ones that a) weren't packages or only written in C, b) only had one Python file (which excluded os.path = posixpath.py/ntpath.py) and c) had docstrings or comments that seemed useful.

datetime and difflib in particular have very good comments (and they're both by Tim Peters).  Possibly controversial: for CSV the patch links to both csv.py and _csv.c; for decimal it links to decimal.py and _decimal.c.  We could exclude these two.
msg214049 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2014-03-19 03:44
+1 on amk’s patch.  I trust his selection of modules, and linking to C module sources can be an interesting experiment.
msg214051 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-03-19 04:38
Without actually looking, I am skeptical of _decimal.c as I expect the code to be highly technical. But maybe it has more helpful comments than I expect. But I am willing to let the person pushing decide. I am overall in favor of linking to python sources.

difflib I know should be linked. tokenize.py (not in the patch) probably should be linked eventually, but only after the docstrings (and doc) are fixed a bit. I will think about it after that is done.
msg214086 - (view) Author: A.M. Kuchling (akuchling) * (Python committer) Date: 2014-03-19 12:26
Terry: yes, the code for _decimal.c doesn't look especially helpful.  (_csv.c is a bit more straightforward, but still isn't highly commented.) The problem is that decimal.py does have long docstrings & discussions, so it's certainly useful.  Is it inconsistent to not link to all the relevant files?  Or is it better to only link to source files that we consider helpful?
msg214111 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-03-19 16:49
With rare exceptions*, my inclination is to only link .py files anyway. Those apply to all implementations that use them as is. Any Python programmer can read them and maybe learn something. The C files only apply to CPython. The possible existence of a _modname accelerator is evident in the Python file. So I suggest applying without the .c links.

*Non-module examples: yesterday on python-list, someone referenced comments in dictobject.c to explain seemingly peculiar behavior. I believe listobject.c has Tim's long comment on .sort.
msg214128 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2014-03-19 20:15
Agreed with Terry.  Some Python modules are just wrappers for C modules, but datetime.py is standalone so we can dispense with the link to _datetime.c.
msg214131 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-03-19 20:25
New changeset bc107f5faedc by Andrew Kuchling in branch 'default':
#13437: link to the source code for a few more modules
http://hg.python.org/cpython/rev/bc107f5faedc
History
Date User Action Args
2014-03-19 20:27:19akuchlingsetstatus: open -> closed
resolution: fixed
stage: commit review -> resolved
2014-03-19 20:25:58python-devsetnosy: + python-dev
messages: + msg214131
2014-03-19 20:15:02eric.araujosetmessages: + msg214128
2014-03-19 16:49:55terry.reedysetmessages: + msg214111
2014-03-19 12:26:02akuchlingsetmessages: + msg214086
2014-03-19 04:38:00terry.reedysetmessages: + msg214051
2014-03-19 03:44:54eric.araujosetstage: commit review
messages: + msg214049
versions: + Python 3.4, Python 3.5, - Python 3.2, Python 3.3
2014-03-18 21:51:27akuchlingsetfiles: + 13437-patch.txt
nosy: + akuchling
messages: + msg214030

2011-11-27 00:21:43Juliansetmessages: + msg148432
2011-11-26 00:18:38terry.reedysetnosy: + terry.reedy
2011-11-21 12:06:15ezio.melottisetmessages: + msg148033
2011-11-21 00:47:19Juliansetmessages: + msg148021
2011-11-20 20:02:48ezio.melottisetnosy: + ezio.melotti
2011-11-20 12:26:20eric.araujosetversions: + Python 3.2
nosy: + rhettinger, eric.araujo

messages: + msg147988

assignee: docs@python -> rhettinger
2011-11-20 00:29:31Juliancreate