[issue9364] some problems with the documentation of pydoc
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 rep...@bugs.python.org http://bugs.python.org/issue9364 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9364] some problems with the documentation of pydoc
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 rep...@bugs.python.org http://bugs.python.org/issue9364 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9364] some problems with the documentation of pydoc
Changes by Glenn Jones gl...@millenniumhand.co.uk: Added file: http://bugs.python.org/file34948/pydoc-2.patch ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9364 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9364] some problems with the documentation of pydoc
Changes by Glenn Jones gl...@millenniumhand.co.uk: Added file: http://bugs.python.org/file34947/_sitebuiltins-2.patch ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9364 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9364] some problems with the documentation of pydoc
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 rep...@bugs.python.org http://bugs.python.org/issue9364 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9364] some problems with the documentation of pydoc
Changes by Nilovna Bascunan-Vasquez cont...@nilovna.com: -- nosy: +nilovna ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9364 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9364] some problems with the documentation of pydoc
Éric Araujo mer...@netwok.org added the comment: yeswanth, would you like more guidance or should I finish the patches? -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9364 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9364] some problems with the documentation of pydoc
Éric Araujo mer...@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 rep...@bugs.python.org http://bugs.python.org/issue9364 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9364] some problems with the documentation of pydoc
Changes by yeswanth swamiyeswa...@yahoo.com: Removed file: http://bugs.python.org/file20686/pydoc.diff ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9364 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9364] some problems with the documentation of pydoc
Changes by yeswanth swamiyeswa...@yahoo.com: Added file: http://bugs.python.org/file20699/pydoc.diff ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9364 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9364] some problems with the documentation of pydoc
yeswanth swamiyeswa...@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 rep...@bugs.python.org http://bugs.python.org/issue9364 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9364] some problems with the documentation of pydoc
Éric Araujo mer...@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 rep...@bugs.python.org http://bugs.python.org/issue9364 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9364] some problems with the documentation of pydoc
Changes by Éric Araujo mer...@netwok.org: -- assignee: docs@python - eric.araujo ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9364 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9364] some problems with the documentation of pydoc
Changes by yeswanth swamiyeswa...@yahoo.com: Removed file: http://bugs.python.org/file20700/site.diff ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9364 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9364] some problems with the documentation of pydoc
Changes by yeswanth swamiyeswa...@yahoo.com: Added file: http://bugs.python.org/file20703/site.diff ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9364 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9364] some problems with the documentation of pydoc
yeswanth swamiyeswa...@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 rep...@bugs.python.org http://bugs.python.org/issue9364 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9364] some problems with the documentation of pydoc
yeswanth swamiyeswa...@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 rep...@bugs.python.org http://bugs.python.org/issue9364 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9364] some problems with the documentation of pydoc
Changes by Ron Adam ron_a...@users.sourceforge.net: -- nosy: +ron_adam ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9364 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9364] some problems with the documentation of pydoc
Eli Bendersky eli...@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 rep...@bugs.python.org http://bugs.python.org/issue9364 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9364] some problems with the documentation of pydoc
Éric Araujo mer...@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 rep...@bugs.python.org http://bugs.python.org/issue9364 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9364] some problems with the documentation of pydoc
Changes by Florent Xicluna florent.xicl...@gmail.com: -- keywords: +easy nosy: +flox stage: - needs patch ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9364 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9364] some problems with the documentation of pydoc
New submission from Eli Bendersky eli...@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: d...@python components: Documentation messages: 111426 nosy: d...@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 rep...@bugs.python.org http://bugs.python.org/issue9364 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
