[Python-Dev] The docs, reloaded (original) (raw)

Nick Craig-Wood nick at craig-wood.com
Thu May 24 11:46:08 CEST 2007

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

More information about the Python-Dev mailing list