[IPython-dev] pydoc and introspective features

[Fernando Perez]

Sorry for not replying earlier, I was caught up in the prep for
PyCon'07 (which I didn't personally attend, but where Brian presented
yesterday two ipython talks).

> > Subject:  pydoc and introspective features
> > From: "Laurent Gautier" <lgautier at gmail.com>
> > Date: Sun, 18 Feb 2007 13:48:28 +0800
> > To: ipython-dev at scipy.org
> >
> >
> > Hi,
> >
> > We are two people in the process of rewriting pydoc for the standard python
> > (with python2.6 as a target), splitting the whole into functional units (modules
> > in a package) and creating the units with extensions outside pydoc in mind.
> > In all honesty, we have no warranty that it will get included but we
> > are committed
> > to release a python module that could replace the existing pydoc anyway.
> >
> > I have been (and remain) an happy user of ipython, and I was thinking that
> > that some of the introspective documention-centered capabilities that we are
> > developing could be of interest to the ipython project.
> >
> > I see that ipython is being rewritten, and that might well be the right moment
> > for me to bring that up and call for comments.
> >
> > Anyone to comment ?

Yes, I think that a more modular pydoc would be great.  Off the top of
my head, a few things:

- search.  This is probably the biggest gripe everyone has with python
vs. commercial interactive systems (such as Matlab or Mathematica).
Tab-completion and 'foo?' work great, but if you don't even know where
to begin looking for something, you're stuck.    A builtin indexing
system that could be either exposed via a web browser or to a
command-line program (such as ipython) would be very welcome by a lot
of users.

- unification with epydoc (or something else)?  I don't know if this
is on the table, but I think that it would be great if the
html-doc-generator from the stdlib were so good that we didn't have to
look for replacement third-party tools.  But I'm not terribly aware of
the internal details and issues, so perhaps you perceive these as
tools with separate purposes.

- easy extensibility.  IPython allows objects to define their own
.getdoc() method to provide documentation in ways that can't be
achieved with a static __doc__ string attribute.  This was added at
user's request, so there's a real-world need for it.  My approach was
a bit ad-hoc, but it would be nice to have a standardized protocol for
objects to expose information about themselves.  If pydoc leads the
way with an officially accepted convention here, ipython will follow
suit.

  This is an area that will require some thought, because ideally
objects should be able to provide information about themselves in the
richest possible way, but that way is dependent on the requester's
environment: for example, is the client capable of HTML or graphical
display, or is it just a terminal?  A generic solution should allow
objects to know the capabilities of the requester, so it can
accordingly provide as rich an information display as the requester
can handle.  A bit of experimentation here may show what a sensible
API for this would be.

- You may want to have a look in ipython's OInspect module, which is
responsible for extracting information about objects.  If pydoc moves
in that direction, feel free to take any code from this that you may
find useful.


Regards,

f