[docs] [issue9364] some problems with the documentation of pydoc

[Éric Araujo]

Éric Araujo <merwok at 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-module (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 at bugs.python.org>
<http://bugs.python.org/issue9364>
_______________________________________