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

Laurent Gautier lgautier at gmail.com
Wed May 23 12:52:43 CEST 2007

2007/5/23, Nick Craig-Wood <nick at craig-wood.com>:

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!

One option is to use a text-mode browser (lynx, links, or the likes).

The other is to develop a terminal mode application (currently in pydoc, I believe)

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?

I really think that making pydoc a solid library to extract/search/navigate the documentation offers a lot of interesting perspectives. When one think beyond the application discussed here, there are a lot of tools (ipython, or any IDE for example) that could make great use of the facility.

[note: Ron and I seemed to disagree on what (and how) pydoc should be, and that in particular, but I keep a keen interest in having such a library.]

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

Python-Dev mailing list Python-Dev at python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/lgautier%40gmail.com

More information about the Python-Dev mailing list