classification
Title: Give proper link in help(idlelib/turtledemo/tkinter.sub/test_*/?)
Type: behavior Stage: test needed
Components: Library (Lib) Versions: Python 3.11
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Joshuah143, docs@python, eric.araujo, martin.panter, r.david.murray, skip.montanaro, terry.reedy, wyz23x2, zach.ware
Priority: normal Keywords: patch

Created on 2020-03-24 05:06 by wyz23x2, last changed 2021-11-08 03:08 by eric.araujo.

Pull Requests
URL Status Linked Edit
PR 29419 open zach.ware, 2021-11-05 06:55
PR 29459 open zach.ware, 2021-11-07 23:09
Messages (15)
msg364917 - (view) Author: wyz23x2 (wyz23x2) * Date: 2020-03-24 05:06
When typing this in shell:
>>> import lib2to3
>>> help(lib2to3)

The output contains this link:
--snip--
MODULE REFERENCE
    https://docs.python.org/3.8/library/lib2to3 <--
    
    The following documentation is automatically generated from the Python
--snip--

But when you access it, 404!
This works:
https://docs.python.org/3.8/library/2to3.html#module-lib2to3

Please change it. Thanks!
msg365232 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2020-03-28 21:18
Lib/lib2to3 is a directory with __init__.py containing
   ### empty
Unlike most python-coded modules, there is no Doc/library/lib2to3.rst and hence no generated lib2to3.html.  Instead, there is a 2to3.rst and 2to3.html.  In the module index, module xyz is usually linked to .../library/xyz.html#module-xyz.  But lib2to3 is somewhere linked instead to .../library/2to3.html#module-lib2to3.

As implied by the changed title, this issue is not at all unique to lib2to3.  Just as lib2to3 implements the command line app 2to3, with 2to3.rst, idlelib implements IDLE with idle.rst.  Turtle demo is domumented within turtle.rst.  Most tkinter submodule have no doc other than a mention within tkinter.rst.  These could perhaps have a # module-tkinter.xyz target added.  (I am not familiar with exactly how.)   But there are also the numerous test modules that have no doc, and the generated doc for these is less useful than the code itself.  

Possible solutions framed in terms of lib2to3:

1. Manual redirection: add lib2to3.rst and hence lib2to3.html with the correct url, possibly with additional text.  But this is not the only module documented within a file with another name, and would not work for things like test files that should not be documented.

2. Auto redirection: persuade whoever manages docs.python.org to add
a redirection for lib2to3.  Fragile.

3. Hardcode the exception in the help output generation.  The latter is generated by pydoc.help.  The module doc location under MODULE REFERENCE is generated by pydoc.Doc.getdocloc.  This function already has a couple of (probably obsolete) tuples of exceptions, so adding more seems OK.

The oddity is that .html is added if and only if the doc location does not start with 'http'.  lines 414-417.I think that this is backwards. It only works because docs.python.org adds missing .html, even to "https://docs.python.org/3.8/library/2to3#module-lib2to3", which is why the bug? has not been noticed.  Note that by default, docloc starts with 'https://', so by default, .html is omitted.

Skip, David, and Martin, you have all modified this part of the code.  Do any of you disagree that there is a bug?
msg365246 - (view) Author: wyz23x2 (wyz23x2) * Date: 2020-03-29 07:40
My opinion:
I think No.2 makes more sense to users that visit the docs directly by https://docs.python.org/3.8/library/lib2to3.html; they will copy the "docs.python.org/version/library/modulename.html" format from other modules. But I also agree it's fragile.
No.3 is good too, according to me. Can use it if No.2 is too fragile.
msg368021 - (view) Author: wyz23x2 (wyz23x2) * Date: 2020-05-04 08:56
Patch?
msg368044 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2020-05-04 12:40
Not until decision made.  And not be me until I have my development machine running.
msg368102 - (view) Author: wyz23x2 (wyz23x2) * Date: 2020-05-05 03:52
OK.
msg374998 - (view) Author: wyz23x2 (wyz23x2) * Date: 2020-08-07 14:39
Ping? Which of the 3 should we choose?
msg404542 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2021-10-20 23:22
This one got caught up in the purge of 2to3 issues, but it's about more than just 2to3.  Reopening.
msg404545 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2021-10-20 23:37
As the title suggested, this is a generic help(module) issue that involves several library modules, including idlelib.  It just happened to be reported for 2to3.  For example, the generated text for 
  import idlelib; help(idlelib)
includes
  MODULE REFERENCE
    https://docs.python.org/3.11/library/idlelib.html
It should be .../idle.html.

The holdup is that I was not then willing to unilaterally decide which of the 3 possible solutions I listed should be pursued.  Maybe just 3, maybe a mix of 1 and 3.
msg404825 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2021-10-22 21:02
Option 3 seems simple and ok to me.
msg405765 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2021-11-05 03:51
Option 4: generate a list of modules (or a mapping of module names to documentation files) that have documentation when generating Lib/pydoc_data/topics.py, and teach pydoc.help to not include the link when it knows the module doesn't have documentation.

This is a much more complete solution that also avoids creating links for private modules (see bpo-45717), but is significantly more effort to implement.
msg405767 - (view) Author: Joshua (Joshuah143) * Date: 2021-11-05 04:43
I think that option 4 would work best but instead of putting any logic in (Lib/pydoc_data/topics.py)[https://github.com/python/cpython/blob/main/Lib/pydoc_data/topics.py] we could put the logic for working with private modules as well and other edge cases in (Lib/pydoc.py)[https://github.com/python/cpython/blob/main/Lib/pydoc.py]. It might make future changes easier.
msg405768 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2021-11-05 06:57
This actually turned out to be less effort than I expected (though I still should have been asleep 2 hours ago), so I've gone ahead and opened GH-29419 to implement what I suggested.
msg405922 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2021-11-08 02:44
PR-29419 solves the issue in #45717 of not giving a link for _* modules with no doc.  It does not solve this issue of giving the proper link for module that need non-standard links, which typically need a '#' suffix, as in '.../library/2to3.html#module-lib2to3'.  I suggest to continue calculating standard links as done now as the precalculation needs much space for a trivial time saving.  Restrict the new dict to non-standard links.  They can be calculated, with the needed suffixes, as they are now for the index.  The link logic would be to try the lookup first and if module name does not start with '_', calculate the link.

I will add an idlelib section to idle.rst so that 'idlelib' appears in the module index and get entered into the exceptions dict.

I don't see how PR-29459 get linked here as it has no reference to this issue.  So I will ignore it at least for know.
msg405923 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2021-11-08 03:08
I think that second PR was linked using the GitHub PR link field present in the bug comment form.
History
Date User Action Args
2021-11-08 03:08:11eric.araujosetmessages: + msg405923
2021-11-08 02:44:17terry.reedysetmessages: + msg405922
stage: patch review -> test needed
2021-11-07 23:09:10zach.waresetstage: test needed -> patch review
pull_requests: + pull_request27713
2021-11-05 06:57:23zach.waresetmessages: + msg405768
stage: patch review -> test needed
2021-11-05 06:55:10zach.waresetkeywords: + patch
stage: test needed -> patch review
pull_requests: + pull_request27672
2021-11-05 04:43:54Joshuah143setnosy: + Joshuah143
messages: + msg405767
2021-11-05 03:54:42zach.warelinkissue45717 superseder
2021-11-05 03:51:28zach.waresetnosy: + zach.ware
messages: + msg405765
2021-10-22 21:02:51eric.araujosetnosy: + eric.araujo
messages: + msg404825
2021-10-20 23:37:10terry.reedysettitle: Dead link in help(idlelib/turtledemo/tkinter.sub/test_*/?) -> Give proper link in help(idlelib/turtledemo/tkinter.sub/test_*/?)
components: - Documentation

nosy: - zach.ware
versions: - Python 3.9, Python 3.10
messages: + msg404545
stage: needs patch -> test needed
2021-10-20 23:22:15zach.waresetstatus: closed -> open

resolution: wont fix ->

stage: resolved -> needs patch
title: Dead link in help(lib2to3/idlelib/turtledemo/tkinter.sub/test_*/?) -> Dead link in help(idlelib/turtledemo/tkinter.sub/test_*/?)
nosy: + zach.ware
versions: + Python 3.11, - Python 3.8
messages: + msg404542
components: + Documentation, Library (Lib), - 2to3 (2.x to 3.x conversion tool)
superseder: Close 2to3 issues and list them here ->
2021-10-20 23:15:17iritkatrielsetstatus: open -> closed
superseder: Close 2to3 issues and list them here
resolution: wont fix
components: + 2to3 (2.x to 3.x conversion tool), - Documentation, Library (Lib)
stage: needs patch -> resolved
2020-08-07 14:40:08wyz23x2setversions: - Python 3.7
2020-08-07 14:39:58wyz23x2setmessages: + msg374998
versions: + Python 3.10
2020-05-05 03:52:08wyz23x2setmessages: + msg368102
2020-05-04 12:40:28terry.reedysetmessages: + msg368044
2020-05-04 08:56:43wyz23x2setmessages: + msg368021
2020-03-29 07:40:15wyz23x2setmessages: + msg365246
2020-03-28 21:18:46terry.reedysettype: performance -> behavior
title: Dead link in help(lib2to3) -> Dead link in help(lib2to3/idlelib/turtledemo/tkinter.sub/test_*/?)
components: - 2to3 (2.x to 3.x conversion tool)

nosy: + skip.montanaro, martin.panter, r.david.murray, terry.reedy
versions: + Python 3.7, Python 3.9
messages: + msg365232
stage: needs patch
2020-03-24 05:06:26wyz23x2create