This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: pydoc getdocloc() is broken
Type: behavior Stage: needs patch
Components: Library (Lib) Versions: Python 3.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: nascheme, r.david.murray, xtreak
Priority: normal Keywords:

Created on 2016-12-08 19:24 by nascheme, last changed 2022-04-11 14:58 by admin.

Files
File name Uploaded Description Edit
pydoc_getdocloc.txt nascheme, 2016-12-08 19:56 review
Messages (3)
msg282729 - (view) Author: Neil Schemenauer (nascheme) * (Python committer) Date: 2016-12-08 19:24
The getdocloc() method in pydoc.py is supposed to return the doc location for modules.  It uses a 'basedir' parameter that is supposed to point to the location of the standard library modules.

That logic is broken for a number of different scenarios, I think.  One is if you build Python in a sub-directory, not in the root of the source tree.  Another I think is if you are using a Zip file for the std lib.

Fixing this properly is not so easy.  One solution would be to explictly mark modules that have docs available.  E.g. create a __pydoc global variable or similar that the 'pydoc' module to inspect.  That would have to be done on every module that has documentation.

Another idea is at build time, crawl through Doc/library and generate a list of modules that have docs.  That's a bit tricky because that generation needs to work on all platforms that Python is built on.

A third idea is to manually add the list to the pydoc.py module.  When new documentation is created under Doc/library, that list would have to be updated.
msg282732 - (view) Author: Neil Schemenauer (nascheme) * (Python committer) Date: 2016-12-08 19:56
Attached is a first pass at the idea of just keeping a list of standard modules that have docs.  I generated the list with:

$ (cd Doc/library; ls *.rst | sed 's/.rst//')

Probably that should be incorporated into the Doc/Makefile somehow.

Perhaps instead of generating a text file, we should generate a Python module that contains a set literal, e.g. Lib/pydoc_data/libs.py.  That would have the advantage of working for frozen distributions or stdlib as Zip files.
msg282735 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-12-08 20:35
It is possible that we only care about this for release builds.  I don't think maintain a hard-coded, hand-coded list is a good idea, regardless.  There might be some way to generate it at build time, though.
History
Date User Action Args
2022-04-11 14:58:40adminsetgithub: 73094
2018-09-18 11:56:33xtreaksetnosy: + xtreak
2016-12-08 20:35:47r.david.murraysetnosy: + r.david.murray
messages: + msg282735
2016-12-08 19:56:39naschemesetfiles: + pydoc_getdocloc.txt

messages: + msg282732
2016-12-08 19:24:29naschemecreate