$ 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
..

+1 to all.  What about the best of both worlds: "MODULE REFERENCE"?

+1 to Georg.  Note that there are people that feel uncomfortable with calling packages modules, but not me.

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.

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?

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?

Committed in r86504 (3.2) and r86505 (3.1).

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.

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.

>> 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.

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?

> 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.

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?

Can I help moving this forward?

MODULE DOCS section is no longer present in pydoc generated pages.