[issue22558] Missing hint to source code - complete

[Terry J. Reedy]

Changes by Terry J. Reedy :


--
versions: +Python 3.6 -Python 3.4

___
Python tracker 

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

[issue22558] Missing hint to source code - complete

[Terry J. Reedy]

Terry J. Reedy added the comment:

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.

--

___
Python tracker 

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

[issue22558] Missing hint to source code - complete

[Guido van Rossum]

Guido van Rossum added the comment:

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!

--

___
Python tracker 

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

[issue22558] Missing hint to source code - complete

[Terry J. Reedy]

Terry J. Reedy added the comment:

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 #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?

--

___
Python tracker 

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

[issue22558] Missing hint to source code - complete

[Guido van Rossum]

Guido van Rossum added the comment:

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

--
keywords: +easy
nosy: +gvanrossum

___
Python tracker 

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

[issue22558] Missing hint to source code - complete

[Alexander Belopolsky]

Alexander Belopolsky added the comment:

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

--
nosy: +belopolsky

___
Python tracker 

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

[issue22558] Missing hint to source code - complete

[Ezio Melotti]

Ezio Melotti added the comment:

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.

--
nosy: +ezio.melotti
stage:  -> needs patch
type:  -> enhancement
versions: +Python 3.4, Python 3.5

___
Python tracker 

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

[issue22558] Missing hint to source code - complete

[Terry J. Reedy]

Terry J. Reedy added the comment:

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

--
nosy: +terry.reedy

___
Python tracker 

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

[issue22558] Missing hint to source code - complete

[Friedrich Spee von Langenfeld]

Friedrich Spee von Langenfeld added the comment:

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?

--
Added file: http://bugs.python.org/file36817/missing_hint_v2.py

___
Python tracker 

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

[issue22558] Missing hint to source code - complete

[R. David Murray]

R. David Murray added the comment:

And that have source code.

That said, some modules may have been consciously omitted.

--
nosy: +r.david.murray, rhettinger

___
Python tracker 

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

[issue22558] Missing hint to source code - complete

[SilentGhost]

SilentGhost added the comment:

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?

--
nosy: +SilentGhost

___
Python tracker 

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

[issue22558] Missing hint to source code - complete

[Friedrich Spee von Langenfeld]

New submission from Friedrich Spee von Langenfeld:

As mentioned in Issue22528, 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?

--
assignee: docs@python
components: Documentation
files: missing_hint.py
messages: 228563
nosy: Friedrich.Spee.von.Langenfeld, docs@python
priority: normal
severity: normal
status: open
title: Missing hint to source code - complete
Added file: http://bugs.python.org/file36812/missing_hint.py

___
Python tracker 

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