Missing doc links to source code for Python-coded modules.

[FriedrichSpeevonLangenfeld]

BPO	22558
Nosy	@rhettinger, @terryjreedy, @abalkin, @ezio-melotti, @bitdancer, @berkerpeksag, @yoniLavi
Files	missing_hint.py missing_hint_v2.py mywork.patch mywork2.patch mywork3.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/terryjreedy'
closed_at = <Date 2016-06-11.19:27:31.915>
created_at = <Date 2014-10-05.13:05:37.443>
labels = ['easy', 'type-feature', 'docs']
title = 'Missing doc links to source code for Python-coded modules.'
updated_at = <Date 2016-06-13.04:16:21.327>
user = 'https://bugs.python.org/FriedrichSpeevonLangenfeld'

bugs.python.org fields:

activity = <Date 2016-06-13.04:16:21.327>
actor = 'Yoni Lavi'
assignee = 'terry.reedy'
closed = True
closed_date = <Date 2016-06-11.19:27:31.915>
closer = 'terry.reedy'
components = ['Documentation']
creation = <Date 2014-10-05.13:05:37.443>
creator = 'Friedrich.Spee.von.Langenfeld'
dependencies = []
files = ['36812', '36817', '42527', '42933', '43252']
hgrepos = []
issue_num = 22558
keywords = ['patch', 'easy']
message_count = 34.0
messages = ['228563', '228564', '228571', '228576', '229015', '230495', '231033', '257574', '257583', '257586', '257602', '263790', '265904', '266000', '266035', '266699', '266835', '266837', '266838', '266846', '266847', '266850', '266857', '267120', '267149', '267173', '267184', '267495', '267540', '268250', '268255', '268299', '268301', '268418']
nosy_count = 12.0
nosy_names = ['rhettinger', 'terry.reedy', 'belopolsky', 'ezio.melotti', 'r.david.murray', 'SilentGhost', 'docs@python', 'python-dev', 'berker.peksag', 'Friedrich.Spee.von.Langenfeld', 'Yoni Lavi', 'nharold']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue22558'
versions = ['Python 3.5', 'Python 3.6']

[FriedrichSpeevonLangenfeld]

As mentioned in bpo-22528, in some modules´ documentation, the link to their source code is missing. To check the stdlib, I´ve written the script missing_hint.py.
It seems that in the following module entries, there aren´t a link to their source code (the last part of output of missing_hint.py):
https://docs.python.org/3/library/aifc.html
https://docs.python.org/3/library/base64.html
https://docs.python.org/3/library/binhex.html
https://docs.python.org/3/library/bz2.html
https://docs.python.org/3/library/cgi.html
https://docs.python.org/3/library/cgitb.html
https://docs.python.org/3/library/chunk.html
https://docs.python.org/3/library/code.html
https://docs.python.org/3/library/codecs.html
https://docs.python.org/3/library/codeop.html
https://docs.python.org/3/library/configparser.html
https://docs.python.org/3/library/copy.html
https://docs.python.org/3/library/copyreg.html
https://docs.python.org/3/library/csv.html
https://docs.python.org/3/library/datetime.html
https://docs.python.org/3/library/decimal.html
https://docs.python.org/3/library/difflib.html
https://docs.python.org/3/library/doctest.html
https://docs.python.org/3/library/fnmatch.html
https://docs.python.org/3/library/formatter.html
https://docs.python.org/3/library/ftplib.html
https://docs.python.org/3/library/getpass.html
https://docs.python.org/3/library/glob.html
https://docs.python.org/3/library/hashlib.html
https://docs.python.org/3/library/imaplib.html
https://docs.python.org/3/library/imp.html
https://docs.python.org/3/library/io.html
https://docs.python.org/3/library/locale.html
https://docs.python.org/3/library/lzma.html
https://docs.python.org/3/library/macpath.html
https://docs.python.org/3/library/mailbox.html
https://docs.python.org/3/library/mimetypes.html
https://docs.python.org/3/library/nntplib.html
https://docs.python.org/3/library/numbers.html
https://docs.python.org/3/library/os.html
https://docs.python.org/3/library/pathlib.html
https://docs.python.org/3/library/pickle.html
https://docs.python.org/3/library/plistlib.html
https://docs.python.org/3/library/poplib.html
https://docs.python.org/3/library/profile.html
https://docs.python.org/3/library/pydoc.html
https://docs.python.org/3/library/py_compile.html
https://docs.python.org/3/library/quopri.html
https://docs.python.org/3/library/re.html
https://docs.python.org/3/library/sched.html
https://docs.python.org/3/library/selectors.html
https://docs.python.org/3/library/shelve.html
https://docs.python.org/3/library/shutil.html
https://docs.python.org/3/library/smtplib.html
https://docs.python.org/3/library/sndhdr.html
https://docs.python.org/3/library/socket.html
https://docs.python.org/3/library/ssl.html
https://docs.python.org/3/library/stat.html
https://docs.python.org/3/library/stringprep.html
https://docs.python.org/3/library/struct.html
https://docs.python.org/3/library/subprocess.html
https://docs.python.org/3/library/telnetlib.html
https://docs.python.org/3/library/tempfile.html
https://docs.python.org/3/library/timeit.html
https://docs.python.org/3/library/traceback.html
https://docs.python.org/3/library/tracemalloc.html
https://docs.python.org/3/library/turtle.html
https://docs.python.org/3/library/uuid.html
https://docs.python.org/3/library/xdrlib.html

Is it possible to add the specific source code link to all of this entries?

[SilentGhost]

Your code produces many false positives, would you care to reduce this list to only those modules that actually do not have a Source code link?

[bitdancer]

And that have source code.

That said, some modules may have been consciously omitted.

[FriedrichSpeevonLangenfeld]

I decremented the shown number of modules by 25. Here is the new list:

https://docs.python.org/3/library/base64.html
https://docs.python.org/3/library/binhex.html
https://docs.python.org/3/library/bz2.html
https://docs.python.org/3/library/cgitb.html
https://docs.python.org/3/library/chunk.html
https://docs.python.org/3/library/code.html
https://docs.python.org/3/library/codecs.html
https://docs.python.org/3/library/codeop.html
https://docs.python.org/3/library/configparser.html
https://docs.python.org/3/library/copy.html
https://docs.python.org/3/library/copyreg.html
https://docs.python.org/3/library/csv.html
https://docs.python.org/3/library/datetime.html
https://docs.python.org/3/library/decimal.html
https://docs.python.org/3/library/difflib.html
https://docs.python.org/3/library/doctest.html
https://docs.python.org/3/library/formatter.html
https://docs.python.org/3/library/getpass.html
https://docs.python.org/3/library/imp.html
https://docs.python.org/3/library/io.html
https://docs.python.org/3/library/locale.html
https://docs.python.org/3/library/lzma.html
https://docs.python.org/3/library/macpath.html
https://docs.python.org/3/library/mailbox.html
https://docs.python.org/3/library/numbers.html
https://docs.python.org/3/library/os.html
https://docs.python.org/3/library/pathlib.html
https://docs.python.org/3/library/pickle.html
https://docs.python.org/3/library/re.html
https://docs.python.org/3/library/selectors.html
https://docs.python.org/3/library/socket.html
https://docs.python.org/3/library/stat.html # false positive
https://docs.python.org/3/library/stringprep.html
https://docs.python.org/3/library/struct.html
https://docs.python.org/3/library/subprocess.html
https://docs.python.org/3/library/traceback.html
https://docs.python.org/3/library/tracemalloc.html
https://docs.python.org/3/library/turtle.html
https://docs.python.org/3/library/uuid.html

@r. David Murray: I will try to look at the source code for each module, but I have updated the list to make it possible to work on this subject in the meantime.

PS: Is it possible for me to edit my own contributions (comments, files) after uploading?

[terryjreedy]

Messages and patches can be unlinked from an issue (and that action recorded in the history list) but not edited. Proofread before clicking.

Originally, only a few module docs had a source code link where the source code was thought to be especially useful. When these links were determined to be useful, more have gradually been added as some developer thought of it or as some user requested, as you did in bpo-22528. I don't know if any requests have been denied. I also don't know if there is a written policy anywhere. To me, it might be easier to link all python sources and be done with the issue.

[ezio-melotti]

The source links have been added where the code proved to be readable, easy to understand, and self documenting, and have been omitted when the code is complicated and not self documenting. This has been done under the assumption that reading the code might help understanding the documentation, but there are other situations where users might want to see the code regardless of how readable it is, so I wouldn't object if you decide to add links to all the modules.

[abalkin]

+1 "to add links to all the [Python] modules"

If the code is not readable, hard to understand or not self-documenting that's the reason to improve the code not to make it harder to find and see.

[gvanrossum]

Actually uploading a patch for this should be easy, right?

[terryjreedy]

Guido, should we take your comment as approving linking every source, as opposed to only some? This scope issue is the main sticking point for this issue. Otherwise, the standard patch is 3 easy new lines after the :synopsis: (and any 'New in Version x.y' note for the module -- see argparse). The following is Benjamin's patch for bpo-22528.

--- a/Doc/library/pdb.rst
+++ b/Doc/library/pdb.rst
@@ -6,6 +6,9 @@
.. module:: pdb
:synopsis: The Python debugger for interactive interpreters.

+Source code: :source:`Lib/pdb.py`
+
+--------------

.. index:: single: debugging

Friedrich, were you planning to write a patch, once the list of modules is decided on? Or should we invite submissions on the core-mentorship list?

[gvanrossum]

It's fine to add a source link to any module for which there is Python source code. I suppose this adds a slight maintenance burden when a module moves (e.g. when a module is turned into a package, or when the subdirectory structure of the Lib directory changes).

I'm a little confused about the "New in x.y" note -- why is that connected to the source code link?

Of course, the source tells a different story from the docs -- e.g. undocumented implementation details may change, and sometimes the source is hard to understand (on occasion I've been confused myself :-). But Python is open source, so people can always read the source -- I don't see why we should try to make reading the source harder for people who don't yet have the chops to just read it on their own computer!

[terryjreedy]

If there is a New-in note (which follows Synopsis), then (to be consistent) the Source note should follow it. If not (the normal situation), then Source follows Synopsis directly.

A point in favor of linking all Python sources from the docs is that default single users installs are much harder to access on Windows than they used to be: /Users/Name/[Appdata - hidden by default]/Roaming?/Python/Pythonxy (I believe) versus the old /Pythonxy.