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

Nick Craig-Wood nick at craig-wood.com
Wed May 23 10:53:00 CEST 2007

Georg Brandl <g.brandl at gmx.net> wrote:

Nick Craig-Wood schrieb: > Being a seasoned unix user, I tend to reach for pydoc as my first stab > at finding some documentation rather than (after excavating the mouse > from under a pile of paper) use a web browser. > > If you've ever used pydoc you'll know it reads docstrings and for some > modules they are great and for others they are sorely lacking. > > If pydoc could show all this documentation as well I'd be very happy! > > Maybe your quick dispatch feature could be added to pydoc too?

It is my intention to work together with Ron Adam to make the pydoc <-> documentation integration as seamless as possible.

So I'll be able to read the main docs for a module in a terminal without reaching for the web browser (or info)? That would be great!

How would pydoc decide which bit of docs it is going to show?

If I type "pydoc re" is it going to give me the rather sparse doc from the re module or the nice reST docs? Or maybe both, one after the other? Or will I have to use a flag to dis-ambiguate?

If you type "pydoc re" at the moment then it says in it

MODULE DOCS http://www.python.org/doc/current/lib/module-re.html

which is pretty much useless to me when ssh-ed in to a linux box half way around the world...

> It is missing conversion of ``comment'' at the moment as I'm sure you > know...

Sorry, what did you mean?

``comment'' produces smart quotes in latex if I remember correctly. You probably want to convert it somehow because it looks a bit odd on the web page as it stands. I'm not sure what the reST replacement might be, but converting it just to "comment" would probably be OK. Likewise with `comment' to 'comment'.

For an example see the first paragraph here:

http://pydoc.gbrandl.de/reference/index.html

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

More information about the Python-Dev mailing list