[issue9364] some problems with the documentation of pydoc
New submission from Eli Bendersky <eliben@gmail.com>: The first paragraph in its documentation says: """ In the Python interpreter, do "from pydoc import help" to provide online help. Calling help(thing) on a Python object documents the object. """ Which is no longer accurate, because the help() function has long ago become a built-in. Below is an excerpt from Terry Reedy in a private email discussion on this subject, that raises more issues. --------------------------------------------- 1. The output from help(help) could be made more clear. The nature of 'help' has been a point of confusion. A recent python-list post asked something like "What is 'help'?" Now (with some parallel examples:
help(int) Help on class int in module builtins:
class int(object) [snip]
help(1) Help on int object:
class int(object) [snip]
help(help) Help on _Helper in module site object:
class _Helper(builtins.object) | Define the built-in 'help'. | This is a wrapper around pydoc.help (with a twist). | | Methods defined here: | | __call__(self, *args, **kwds) | a. 'module site object' is nonsense, it should just be 'module site', except that to be parallel to what is done for other instances, it should be 'Help on _Helper object'. Why should help special-case itself (with a slightly garbled line?) Is that done in site._Helper or pydoc.help? However, it would be more helpful for all instances to give the location of the class when one asks for help on an instance, just as when one asks for help on the class itself. It is annoying to to have to repeat help(<classname>) just to get that info. So I would like to see "Help on instance of class int in module builtins:" "Help on instance of class _Helper in module site:" This would be a code patch to pydoc.help b. "This is a wrapper around pydoc.help" good so far "(with a twist)" thanks a lot. I think the comment should be either removed or explained. A reference manual should explain, not tease. Replace "Define the built-in 'help'." with something clearer and more accurate, such as "The name 'help' is injected in module builtins after being bound to an instance of this class.". Put this after, not before, the 'wrapper' line. A patch for site._Helper doc string. 2. Improve manual chapter for site module. a. It currently starts "Importing this module will append site-specific paths to the module search path." Add "inject 'help' into builtins and " after append. Then add a short explanation paragraph before the search path stuff. Something like "This module contains a class (_Helper) that wraps function pydoc.help. An instance of the class is bound to name 'help' in the builtins module." A recent discussion on pydev or maybe python-list (in the thread mentioned above?) implied that one could usefully make another instance of _Helper or maybe a subclass thereof. I did not pay enough attention, though, to really get it. b. It currently ends with "XXX Update documentation XXX document python -m site –user-base –user-site" ---------- assignee: docs@python components: Documentation messages: 111426 nosy: docs@python, eli.bendersky, tjreedy priority: normal severity: normal status: open title: some problems with the documentation of pydoc type: behavior versions: Python 3.1, Python 3.2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9364> _______________________________________
Changes by Florent Xicluna <florent.xicluna@gmail.com>: ---------- keywords: +easy nosy: +flox stage: -> needs patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9364> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment:
In the Python interpreter, do "from pydoc import help" to provide online help. Calling help(thing) on a Python object documents the object. Which is no longer accurate, because the help() function has long ago become a built-in. To be pedantic, help is not available if python was started with -S. (The docs for site and -S are cross-linked, so that should be discoverable easily enough.) +1 on removing the outdated piece of advice.
1. The output from help(help) could be made more clear. Agreed.
Why should help special-case itself (with a slightly garbled line?) This would be a code patch to pydoc.help I haven’t found any special-casing code. Quick testing shows it’s just how pydoc displays help for instances of Python classes. I think making the docstring of site._Helper better (i.e. explain what the class is for + tell people to call help() to access the doc system) would be enough, nothing to change in pydoc.py unless I’ve missed something.
(BTW, pydoc code is quite intricated, reminds me a bit of distutils! Who wants to make a graph explaining how help works?)
"This is a wrapper around pydoc.help" good so far "(with a twist)" thanks a lot. I think the comment should be either removed or explained. Agreed. I think the “twist” is that the import is lazy and that help has a useful repr (wow, talk about a twist!). Those details need not be alluded to, just remove the comment (“wrapper” is IMO enough to raise curiosity, the source is here to find what’s the wrapping).
Replace "Define the built-in 'help'." with something clearer and more accurate, such as "The name 'help' is injected in module builtins after being bound to an instance of this class.". I think that’s too much detail. “Class used to implement the built-in help function” is enough for my taste.
2. Improve manual chapter for site module. +1 on better explaining behavior where needed, -1 on documenting implementation details starting with underscores.
Add "inject 'help' into builtins and " after append. -1. help is documented in http://docs.python.org/dev/library/functions#help ; quit, exit, license, copyright and credits are documented in http://docs.python.org/dev/library/constants#constants-added-by-the-site-mod... (see #652749). To prevent duplication, let’s just add a link from site to constants.
(You don’t want to know how much time the previous paragraph has cost me.)
"This module contains a class (_Helper) that wraps function pydoc.help. An instance of the class is bound to name 'help' in the builtins module." -1. Counter-proposal: Add a link to library/functions#help from library/constants; add a link from library/site to library/constants.
A recent discussion on pydev or maybe python-list (in the thread mentioned above?) implied that one could usefully make another instance of _Helper or maybe a subclass thereof. I did not pay enough attention, though, to really get it. I’m curious about the use cases. Eli, can you give us the date of the private email from Terry so that someone can dig up the thread?
"XXX Update documentation" This comment refers to new functions in site to support PEP 370.
"XXX document python -m site --user-base --user-site" We can reuse the example written by Raymond for the whatsnew/3.2 document.
To sum up: needs one patch for Lib/site.py, one to add cross-links in Doc/library, one to add missing functions/data from PEP 370 in Doc/library/site.rst, another one to the same file to document the command-line interface of site (those last two may be one, if the contributor is motivated). I suggest to wait for replies to my points above, and if there is consensus or lack of disagreement, someone can turn my suggestions into patches. ---------- nosy: +eric.araujo versions: +Python 2.7, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9364> _______________________________________
Changes by Ron Adam <ron_adam@users.sourceforge.net>: ---------- nosy: +ron_adam _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9364> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment: Éric - your suggestions look good to me. The correspondence with Terry was on July 16th, 2010 - maybe he can remember which thread in pydev it was exactly. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9364> _______________________________________
yeswanth <swamiyeswanth@yahoo.com> added the comment: Suggestions are good . One thing I came across when going through the doc is that when you run help(help) after importing help from pydoc , i noticed that the first line of the help utility is """ Welcome to Python 3.2! This is the online help utility. """ which could be changed to "Welcome to Python help utility" as the help utility is already inbuilt . ---------- nosy: +swamiyeswanth _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9364> _______________________________________
yeswanth <swamiyeswanth@yahoo.com> added the comment: Patch for the change i have suggested in pydoc . @Eric I will try to implement the patch suggestions you have made. I still have to figure out how to make crosslinks ---------- keywords: +patch Added file: http://bugs.python.org/file20686/pydoc.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9364> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment:
Welcome to Python 3.2! This is the online help utility. which could be changed to Welcome to Python help utility
Agreed. I assume this dates back to a time where “online help” meant available on this computer, not on some global network. I’d keep the version in the string, though: Welcome to Python 3.2's help utility! ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9364> _______________________________________
Changes by yeswanth <swamiyeswanth@yahoo.com>: Removed file: http://bugs.python.org/file20686/pydoc.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9364> _______________________________________
Changes by yeswanth <swamiyeswanth@yahoo.com>: Added file: http://bugs.python.org/file20699/pydoc.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9364> _______________________________________
yeswanth <swamiyeswanth@yahoo.com> added the comment: Completely agreed with you on having "Welcome to python 3.2 help!".. made the changes. Uploaded site.py as suggested by you . I will try to create the patch for the links , but i am not sure how to .Could use some help if you can provide me any website link.Thanks ---------- Added file: http://bugs.python.org/file20700/site.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9364> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: See http://docs.python.org/dev/documenting/ (see also http://docs.python.org/devguide/patch for process guidelines). Note about site.diff: - """Define the builtin 'help'. - This is a wrapper around pydoc.help (with a twist). + """Class used to implement the built-in help function I suggested to remove “with a twist”, not the other part of the line. The other patch is fine, thanks. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9364> _______________________________________
Changes by Éric Araujo <merwok@netwok.org>: ---------- assignee: docs@python -> eric.araujo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9364> _______________________________________
Changes by yeswanth <swamiyeswanth@yahoo.com>: Removed file: http://bugs.python.org/file20700/site.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9364> _______________________________________
Changes by yeswanth <swamiyeswanth@yahoo.com>: Added file: http://bugs.python.org/file20703/site.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9364> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: yeswanth, would you like more guidance or should I finish the patches? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9364> _______________________________________
Changes by Nilovna Bascunan-Vasquez <contact@nilovna.com>: ---------- nosy: +nilovna _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9364> _______________________________________
Changes by Glenn Jones <glenn@millenniumhand.co.uk>: Added file: http://bugs.python.org/file34947/_sitebuiltins-2.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9364> _______________________________________
Changes by Glenn Jones <glenn@millenniumhand.co.uk>: Added file: http://bugs.python.org/file34948/pydoc-2.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9364> _______________________________________
Glenn Jones added the comment: I have added patches that replace the previous ones and apply to head. It appears that the other changes discussed (crosslinking and improving documentation) have already been done. ---------- nosy: +Glenn.Jones _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9364> _______________________________________
Roundup Robot added the comment: New changeset 16207b8495bf by R David Murray in branch '3.4': #9364: Improve the text printed by help(pydoc) and help(help). http://hg.python.org/cpython/rev/16207b8495bf New changeset 256c782ab078 by R David Murray in branch 'default': Merge: #9364: Improve the text printed by help(pydoc) and help(help). http://hg.python.org/cpython/rev/256c782ab078 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9364> _______________________________________
R. David Murray added the comment: Thanks, Glenn. I tweaked the wording further. If someone thinks it is worth the effort to backport this to 2.7, they can do so and reopen the issue. ---------- assignee: eric.araujo -> nosy: +r.david.murray resolution: -> fixed stage: needs patch -> resolved status: open -> closed versions: +Python 3.4, Python 3.5 -Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9364> _______________________________________
participants (9)
-
Eli Bendersky -
Florent Xicluna
-
Glenn Jones
-
Nilovna Bascunan-Vasquez
-
R. David Murray
-
Ron Adam
-
Roundup Robot
-
yeswanth
-
Éric Araujo