| msg121365 - (view) |
Author: Alexander Belopolsky (belopolsky) *  |
Date: 2010-11-17 17:32 |
| $ 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 <ping@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 .. |
|
|
| msg121373 - (view) |
Author: Georg Brandl (georg.brandl) * |
Date: 2010-11-17 18:31 |
| +1 to all. What about the best of both worlds: "MODULE REFERENCE"? |
|
|
| msg121384 - (view) |
Author: Éric Araujo (eric.araujo) * |
Date: 2010-11-17 21:03 |
| +1 to Georg. Note that there are people that feel uncomfortable with calling packages modules, but not me. |
|
|
| msg121391 - (view) |
Author: Alexander Belopolsky (belopolsky) * |
Date: 2010-11-17 23:00 |
| The attached patch, .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. |
|
|
| msg121394 - (view) |
Author: Éric Araujo (eric.araujo) * |
Date: 2010-11-18 00:27 |
| 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? |
|
|
| msg121399 - (view) |
Author: Alexander Belopolsky (belopolsky) * |
Date: 2010-11-18 01:01 |
| On Wed, Nov 17, 2010 at 7:28 PM, Éric Araujo <report@bugs.python.org> wrote: > > Éric Araujo <merwok@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? |
|
|
| msg121416 - (view) |
Author: Alexander Belopolsky (belopolsky) * |
Date: 2010-11-18 02:09 |
| Committed in r86504 (3.2) and r86505 (3.1). |
|
|
| msg121423 - (view) |
Author: Alexander Belopolsky (belopolsky) * |
Date: 2010-11-18 02:24 |
| 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. |
|
|
| msg121436 - (view) |
Author: Ron Adam (ron_adam) * |
Date: 2010-11-18 04:21 |
| 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. |
|
|
| msg121437 - (view) |
Author: Éric Araujo (eric.araujo) * |
Date: 2010-11-18 04:26 |
| >> 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. |
|
|
| msg121438 - (view) |
Author: Alexander Belopolsky (belopolsky) * |
Date: 2010-11-18 05:03 |
| On Wed, Nov 17, 2010 at 11:26 PM, Éric Araujo <report@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? |
|
|
| msg121439 - (view) |
Author: Éric Araujo (eric.araujo) * |
Date: 2010-11-18 05:06 |
| > 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. |
|
|
| msg121441 - (view) |
Author: Alexander Belopolsky (belopolsky) * |
Date: 2010-11-18 05:25 |
| On Wed, Nov 17, 2010 at 11:21 PM, Ron Adam <report@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? |
|
|
| msg138000 - (view) |
Author: Éric Araujo (eric.araujo) * |
Date: 2011-06-09 16:12 |
| Can I help moving this forward? |
|
|
| msg221911 - (view) |
Author: Alexander Belopolsky (belopolsky) * |
Date: 2014-06-29 22:43 |
| MODULE DOCS section is no longer present in pydoc generated pages. |
|
|