[issue10446] pydoc3 links to 2.x library reference

Alexander Belopolsky report at bugs.python.org
Thu Nov 18 06:25:06 CET 2010


Alexander Belopolsky <belopolsky at users.sourceforge.net> added the comment:

On Wed, Nov 17, 2010 at 11:21 PM, Ron Adam <report at 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 <report at bugs.python.org>
<http://bugs.python.org/issue10446>
_______________________________________


More information about the Python-bugs-list mailing list