help/info, graphical help browser (was: [SciPy-dev] gsl and scipy)

[arnd.baecker at physik.uni-ulm.de]

Hi,

this started with my question and Travis answer to it:

> > A (slightly) related question: the output of
> >   help(scipy.special.airy)
> > is, well, not really helpful.
>
> Use
>
> info(scipy.special.airy)
>
> if you have Scipy-0.2 and greater and Python 2.2

Thanks - I fear that I should have know that somehow ...

> What is not helpful about that output? (aside from the fact that
> (Ai,Bi,Aip,Bip) is not shown as the output --- due to the autodoc
> generator for these ufuncs.

That output is indeed helpful - apart from what you just mentioned.
  (there seems to be also a line wrapping issue:
  From the ouput of scipy.info(scipy.special.airy)
  compared with scipy.special.airy.__doc__
  I think the \n should be before "derivative" - but that is _really_ of
  minor importance. Is this text - including the line-wrapping-
  generated automatically ?)

I think it would be good to have
 a) that (Ai,Bi,Aip,Bip)  is shown as the output.
 b) an example (or several examples ;-)

Of course, this should be done for most of the routines, if possible.
Surely b) is something for the future (after 0.2, I'd guess).

Which of course means to write the docs - I think that this
would be a good thing for the users to contribute
(which presumably means to setup a mechanism and some brief guidelines
how to do this ...).

> In Python 2.2 help uses a different facility which apparently cannot
> read the docstrings of builtin functions (a limititation in my view).

I had a look at that recently in a different context and I
think it uses pydoc in the end (please correct me if I am wrong here).
I have no idea how easy it would be to change that ...

More generally  I think that in the long run scipy
needs a good help system (don't get me wrong the
current status is already quite good!).
In particular I would like a graphical help browser
- so that one could type something like
  ghelp
or
  ghelp(topic)
to pop up the graphical help.
The graphical help could/should contain: Package indices,
routine descriptions, examples, cross-references,
further docu, tutorials etc. and a good search engine.
It should be also extensible in an easy
way (for example to cover IPython, etc etc as well).

There are surely many more things to think of ...

Would be Tkinter (with for example tkhtml to browse
html docu) a good choice for this ?
(what about qt, wxPython, anygui (to early, I fear))
((personally, I don't like to use a big browser like
mozilla for this ...))

In any case, is this something which more than one person
finds useful/helpful or even necessary for scipy ?
Would it make sense to discuss the design in more detail here ?

There are some approches which offer some of the
functionality

pydoc -g
dox      http:/dox.berlios.de/
devhelp  http://www.devhelp.net/
'microsoft html help': http://www.orgmf.com.ar/condor/pytstuff.html#python
pyhelp at http://starship.python.net/crew/theller/pyhelp.cgi

Arnd