[issue10446] pydoc3 links to 2.x library reference
Alexander Belopolsky added the comment: MODULE DOCS section is no longer present in pydoc generated pages. -- resolution: accepted - out of date status: open - closed ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue10446 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue10446] pydoc3 links to 2.x library reference
Éric Araujo mer...@netwok.org added the comment: Can I help moving this forward? -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue10446 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue10446] pydoc3 links to 2.x library reference
New submission from Alexander Belopolsky belopol...@users.sourceforge.net: $ pydoc3.1 pydoc Help on module pydoc: NAME pydoc - Generate Python documentation in HTML or text for interactive use. FILE /opt/local/Library/Frameworks/Python.framework/Versions/3.1/lib/python3.1/pydoc.py MODULE DOCS http://docs.python.org/library/pydoc I suggest changing the default base URL to http://docs.python.org/release/X.Y.Z I would also like to take this opportunity and make some other improvements: 1. Clarify that the linked document is the authoritative reference and that generated documentation may expose functions that are considered internal and subject to change or removal. (Suggestions for an exact wording are welcome.) 2. Move the FILE section to the end. This will free up some screen space for an expanded AUTHORITATIVE REFERENCE section. (Yes, I think the section title MODULE DOCS can be improved, but my mind is not set on any particular alternative.) 3. Do not include __special__ names in the DATA section. At the very least, exclude __author__, __version__, and other special names that cause generation of document sections: DATA __author__ = 'Ka-Ping Yee p...@lfw.org' __credits__ = 'Guido van Rossum, for an excellent programming l...erla... __date__ = '26 February 2001' __version__ = '$Revision: 78210 $' VERSION 78210 DATE 26 February 2001 .. -- assignee: belopolsky components: Documentation, Library (Lib) messages: 121365 nosy: belopolsky priority: normal severity: normal status: open title: pydoc3 links to 2.x library reference type: behavior versions: Python 3.1, Python 3.2 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue10446 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue10446] pydoc3 links to 2.x library reference
Changes by Alexander Belopolsky belopol...@users.sourceforge.net: -- nosy: +d...@python ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue10446 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue10446] pydoc3 links to 2.x library reference
Georg Brandl ge...@python.org added the comment: +1 to all. What about the best of both worlds: MODULE REFERENCE? -- nosy: +georg.brandl ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue10446 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue10446] pydoc3 links to 2.x library reference
Éric Araujo mer...@netwok.org added the comment: +1 to Georg. Note that there are people that feel uncomfortable with calling packages modules, but not me. -- nosy: +eric.araujo ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue10446 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue10446] pydoc3 links to 2.x library reference
Alexander Belopolsky belopol...@users.sourceforge.net added the comment: The attached patch, issue10446.diff, makes help(sys) look as follows: NAME sys MODULE REFERENCE http://docs.python.org/release/3.2/library/sys The following documentation is automatically generated from the Python source files. It may be incomplete, incorrect or include features that are considered implementation detail and may vary between Python implementations. When in doubt, consult the module reference at the location listed above. DESCRIPTION This module provides access to some objects used or maintained by the interpreter and to functions that interact strongly with the interpreter. .. Georg, I noticed that there is no http://docs.python.org/release/3.2 link yet, but I don't want to complicate the URL generation logic unnecessarily to accommodate pre-release versions. If you can suggest some simple test for pointing to 'dev' instead of 'release/X.Y', I'll add it, but I don't see it as a priority. If you test the patch from the source tree, please note that pydoc has some strange logic that excludes uninstalled modules except ones in a hardcoded list. This should be changed at some point. -- keywords: +patch Added file: http://bugs.python.org/file19629/issue10446.diff ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue10446 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue10446] pydoc3 links to 2.x library reference
Changes by Alexander Belopolsky belopol...@users.sourceforge.net: -- stage: - patch review ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue10446 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue10446] pydoc3 links to 2.x library reference
Éric Araujo mer...@netwok.org added the comment:
Looks good. Some remarks:
1) I assume you have checked that this code does not produce two newlines (one
in the string, one from the print function or write method):
+[snip], consult the module reference at the location listed above.
+)
2) “If you can suggest some simple test for pointing to 'dev' instead of
'release/X.Y'” → sys.version_info[3] != 'final'
3) People seem to go the the most recent version of the docs, not the
release-specific version (I haven’t found the python-dev thread about that,
maybe you remember it). The version{add,chang}ed directives help adjust the
doc for older versions. So, are you sure it’s useful to make the links
release-specific?
--
___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue10446
___
___
Python-bugs-list mailing list
Unsubscribe:
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue10446] pydoc3 links to 2.x library reference
Alexander Belopolsky belopol...@users.sourceforge.net added the comment:
On Wed, Nov 17, 2010 at 7:28 PM, Éric Araujo rep...@bugs.python.org wrote:
Éric Araujo mer...@netwok.org added the comment:
Looks good. Some remarks:
1) I assume you have checked that this code does not produce two newlines
(one in the string,
one from the print function or write method):
Yes, it should be clear from the output that I presented above. I
think TextDoc.indent() takes care of the trailing '\n'.
That won't work for maintenance branches. (I am not even sure docs are
built for maintenance branches.)
3) People seem to go the the most recent version of the docs, not the
release-specific version
(I haven’t found the python-dev thread about that, maybe you remember it).
The version{add,chang}ed directives help adjust the doc for older versions.
So, are you sure it’s useful to make the links release-specific?
Certainly. If we are talking about the most authoritative source. I
don't think versionadded/changed tags are reliable enough and you
don't want to send users to wrong docs when APIs change between
releases. I am not so sure about micro-version, but there is no easy
way to construct the latest micro-version link without changes on
python.org. If there was say latest/X.Y, I would use that. Wait -
there is: docs.python.org/X.Y. Would you prefer that?
--
___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue10446
___
___
Python-bugs-list mailing list
Unsubscribe:
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue10446] pydoc3 links to 2.x library reference
Alexander Belopolsky belopol...@users.sourceforge.net added the comment: Committed in r86504 (3.2) and r86504 (3.1). -- resolution: - accepted stage: patch review - committed/rejected status: open - closed ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue10446 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue10446] pydoc3 links to 2.x library reference
Alexander Belopolsky belopol...@users.sourceforge.net added the comment: s/r86504 (3.1)/r86505 (3.1)/ -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue10446 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue10446] pydoc3 links to 2.x library reference
Alexander Belopolsky belopol...@users.sourceforge.net added the comment: Committed in r86504 (3.2) and r86505 (3.1). -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue10446 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue10446] pydoc3 links to 2.x library reference
Changes by Alexander Belopolsky belopol...@users.sourceforge.net: -- Removed message: http://bugs.python.org/msg121414 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue10446 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue10446] pydoc3 links to 2.x library reference
Changes by Alexander Belopolsky belopol...@users.sourceforge.net: -- Removed message: http://bugs.python.org/msg121412 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue10446 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue10446] pydoc3 links to 2.x library reference
Alexander Belopolsky belopol...@users.sourceforge.net added the comment: Reopening to consider changing just the link (not other changes) in 2.7. At some point http://docs.python.org/library will point to 3.x and we get a bug in 2.7. -- status: closed - open versions: +Python 2.7 -Python 3.1, Python 3.2 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue10446 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue10446] pydoc3 links to 2.x library reference
Ron Adam ron_a...@users.sourceforge.net added the comment: I noticed in your patch, the disclaimer only prints when pydoc can find a doc location (docloc is not None). So it may not get displayed at all depending on how python is installed. I also think having it on every page may be a bit overly cautious. (IMHO) I'm also not sure it is correct to have that when viewing third party modules as the doc location in those cases will be broken anyway. The obvious places to put it are: * top of the pydoc html module index. (first page displayed) * in the welcome message for interactive help() * help(help) * help(pydoc) It can still be defined in one location and then use + pydoc_disclaimer in the desired locations. -- nosy: +ron_adam ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue10446 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue10446] pydoc3 links to 2.x library reference
Éric Araujo mer...@netwok.org added the comment: 1) I assume you have checked that this code does not produce two newlines (one in the string, one from the print function or write method): Yes, it should be clear from the output that I presented above. Okay, I had missed that. I think TextDoc.indent() takes care of the trailing '\n'. What is take care? Removing it? That won't work for maintenance branches. (I am not even sure docs are built for maintenance branches.) 3.1 and 2.7 docs are rebuilt. I am not so sure about micro-version There is only one version* directive which uses a micro number. It’s a bit unfortunate. If there was say latest/X.Y, I would use that. Wait - there is: docs.python.org/X.Y. Would you prefer that? My point was that people used 2.7 docs even when developing for 2.6. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue10446 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue10446] pydoc3 links to 2.x library reference
Alexander Belopolsky belopol...@users.sourceforge.net added the comment: On Wed, Nov 17, 2010 at 11:26 PM, Éric Araujo rep...@bugs.python.org wrote: .. If there was say latest/X.Y, I would use that. Wait - there is: docs.python.org/X.Y. Would you prefer that? My point was that people used 2.7 docs even when developing for 2.6. The point of this bug report was that 3.x pydoc was sending users to 2.7, which is clearly unacceptable. As long as documentation bug fixes are backported to maintenance branches, I don't see an advantage in consulting 3.2 when developing for 3.1. Now, I keep this issue open to decide if we should backport this to 2.7 where this is not a bug (yet), but will be when default docs switch to 3.x. What do you think? -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue10446 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue10446] pydoc3 links to 2.x library reference
Éric Araujo mer...@netwok.org added the comment: The point of this bug report was that 3.x pydoc was sending users to 2.7, which is clearly unacceptable. Agreed. My reply about x.y vs. x.y+1 was a reaction to your patch, not a misunderstanding of the point of this bug. As long as documentation bug fixes are backported to maintenance branches, I don't see an advantage in consulting 3.2 when developing for 3.1. I prefer version-specific docs too, but the thread on python-dev seemed to show I was not in the majority. Now, I keep this issue open to decide if we should backport this to 2.7 where this is not a bug (yet), but will be when default docs switch to 3.x. What do you think? +1 for backporting. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue10446 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue10446] pydoc3 links to 2.x library reference
Alexander Belopolsky belopol...@users.sourceforge.net added the comment: On Wed, Nov 17, 2010 at 11:21 PM, Ron Adam rep...@bugs.python.org wrote: .. I noticed in your patch, the disclaimer only prints when pydoc can find a doc location (docloc is not None). This is not a disclaimer, but an explanation of the relationship between pydoc pages and the reference manual. So it may not get displayed at all depending on how python is installed. docloc should not be None for standard library modules. This is a separate issue. I also think having it on every page may be a bit overly cautious. (IMHO) In text viewer you only see one page at a time. In HTML you may put it on the index or start page. docloc is None for 3rd party modules (pydocs checks for site-packages component in path). The logic is not very robust, but that is a separate issue. That's fine. No, these places are almost never seen. Also, one should not think of this as a disclaimer, but as an explanation of why she is shown a link to a reference page when full documentation is already displayed. It can still be defined in one location and then use + pydoc_disclaimer in the desired locations. Sure. Just don't call it disclaimer. Maybe Doc.REFTEXT constant next to Doc.PYTHONDOCS? -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue10446 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue10446] pydoc3 links to 2.x library reference
Alexander Belopolsky belopol...@users.sourceforge.net added the comment: On Wed, Nov 17, 2010 at 11:21 PM, Ron Adam rep...@bugs.python.org wrote: .. I noticed in your patch, the disclaimer only prints when pydoc can find a doc location (docloc is not None). This is not a disclaimer, but an explanation of the relationship between pydoc pages and the reference manual. So it may not get displayed at all depending on how python is installed. docloc should not be None for standard library modules. This is a separate issue. I also think having it on every page may be a bit overly cautious. (IMHO) In text viewer you only see one page at a time. In HTML you may put it on the index or start page. I'm also not sure it is correct to have that when viewing third party modules as the doc location in those cases will be broken anyway. docloc is None for 3rd party modules (pydocs checks for site-packages component in path). The logic is not very robust, but that is a separate issue. The obvious places to put it are: * top of the pydoc html module index. (first page displayed) That's fine. * in the welcome message for interactive help() * help(help) * help(pydoc) No, these places are almost never seen. Also, one should not think of this as a disclaimer, but as an explanation of why she is shown a link to a reference page when full documentation is already displayed. It can still be defined in one location and then use + pydoc_disclaimer in the desired locations. Sure. Just don't call it disclaimer. Maybe Doc.REFTEXT constant next to Doc.PYTHONDOCS? -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue10446 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue10446] pydoc3 links to 2.x library reference
Changes by Alexander Belopolsky belopol...@users.sourceforge.net: -- Removed message: http://bugs.python.org/msg121440 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue10446 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
