[issue9364] some problems with the documentation of pydoc
New submission from Eli Bendersky
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
Changes by Florent Xicluna
Éric Araujo
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
Changes by Ron Adam
Eli Bendersky
yeswanth
yeswanth
Éric Araujo
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
Changes by yeswanth
Changes by yeswanth
yeswanth
Éric Araujo
Changes by Éric Araujo
Changes by yeswanth
Changes by yeswanth
Éric Araujo
Changes by Nilovna Bascunan-Vasquez
Changes by Glenn Jones
Changes by Glenn Jones
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
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
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
participants (9)
-
Eli Bendersky -
Florent Xicluna
-
Glenn Jones
-
Nilovna Bascunan-Vasquez
-
R. David Murray
-
Ron Adam
-
Roundup Robot
-
yeswanth
-
Éric Araujo