[Python-Dev] The docs, reloaded

[Laurent Gautier]

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
>