[Python-Dev] The docs, reloaded

[Nick Craig-Wood]

On Wed, May 23, 2007 at 05:39:38AM -0500, skip at pobox.com wrote:
>     Nick> If you type "pydoc re" at the moment then it says in it
> 
>     Nick>   MODULE DOCS
>     Nick>       http://www.python.org/doc/current/lib/module-re.html
> 
>     Nick> which is pretty much useless to me when ssh-ed in to a linux box
>     Nick> half way around the world...
> 
> I get quite a bit of information about re (I've never known /F to be a
> documentation slouch).

Yes it is certainly better than no docs.  It doesn't for instance have
any regexp info, and I can never remember all the special non matching
brackets (eg (?:...) so I have to read for the full docs for that.

> Only one bit of that information is a reference to the page in the
> library reference manual.  And if I happen to be ssh'd into a
> machine halfway round the world through a Gnome terminal I can right
> mouse over that URL and pop the page up in my default local browser.
> If you set the PYTHONDOCS environment variable you can point it to a
> local (or at least different) copy of the libref manual.

I take your point.

However the unix tradition is that everything is in the man pages.
man pages have expanded over the years to include info pages and you
*can* read the full python docs via info, it just isn't quite as
convenient as pydoc.

I think perl had the right idea with perldoc.  You can read all the
perl documentation whether it is in module documentation (like
docstrings) or general documentation (like the latex docs under
discussion).

I'd like to see pydoc be a viewer for all the python documentation,
not just a subset of it.

> A flag could be added to pydoc to show that content instead, however
> being html it probably would be difficult to read unless pumped
> through lynx -dump or something similar.

I'm assuming that we do reST all the python documentation which would
make it easier.

-- 
Nick Craig-Wood <nick at craig-wood.com> -- http://www.craig-wood.com/nick