[issue13437] Provide links to the source code for every module in the documentation

[A.M. Kuchling]

Changes by A.M. Kuchling :


--
resolution:  -> fixed
stage: commit review -> committed/rejected
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue13437] Provide links to the source code for every module in the documentation

[Roundup Robot]

Roundup Robot added the comment:

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

--
nosy: +python-dev

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue13437] Provide links to the source code for every module in the documentation

[Éric Araujo]

Éric Araujo added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue13437] Provide links to the source code for every module in the documentation

[Terry J. Reedy]

Terry J. Reedy added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue13437] Provide links to the source code for every module in the documentation

[A.M. Kuchling]

A.M. Kuchling added the comment:

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?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue13437] Provide links to the source code for every module in the documentation

[Terry J. Reedy]

Terry J. Reedy added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue13437] Provide links to the source code for every module in the documentation

[Éric Araujo]

Éric Araujo added the comment:

+1 on amk’s patch.  I trust his selection of modules, and linking to C module 
sources can be an interesting experiment.

--
stage:  -> commit review
versions: +Python 3.4, Python 3.5 -Python 3.2, Python 3.3

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue13437] Provide links to the source code for every module in the documentation

[A.M. Kuchling]

A.M. Kuchling added the comment:

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.

--
nosy: +akuchling
Added file: http://bugs.python.org/file34499/13437-patch.txt

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue13437] Provide links to the source code for every module in the documentation

[Julian Berman]

Julian Berman  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue13437] Provide links to the source code for every module in the documentation

[Terry J. Reedy]

Changes by Terry J. Reedy :


--
nosy: +terry.reedy

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue13437] Provide links to the source code for every module in the documentation

[Ezio Melotti]

Ezio Melotti  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue13437] Provide links to the source code for every module in the documentation

[Julian Berman]

Julian Berman  added the comment:

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).

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue13437] Provide links to the source code for every module in the documentation

[Ezio Melotti]

Changes by Ezio Melotti :


--
nosy: +ezio.melotti

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue13437] Provide links to the source code for every module in the documentation

[Éric Araujo]

Éric Araujo  added the comment:

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.

--
assignee: docs@python -> rhettinger
nosy: +eric.araujo, rhettinger
versions: +Python 3.2

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue13437] Provide links to the source code for every module in the documentation

[Julian Berman]

New submission from Julian Berman :

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?).

--
assignee: docs@python
components: Documentation
messages: 147973
nosy: Julian, docs@python
priority: normal
severity: normal
status: open
title: Provide links to the source code for every module in the documentation
type: feature request
versions: Python 2.7, Python 3.3

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com