[SciPy-dev] Using IPython

[Fernando Pérez]

On Sun, 17 Feb 2002, Janko Hauser wrote:

> It was more a headsup, that the scipy folks need to make a descision
> about this. I would like to use pydoc as you did in ipython. And you
> were right IMO to ripp of the html-based thing. I write the html-doc's
> more to be a kind of handbook, which would be a good place to give
> more examples, links between functions and short overview chapters. I
> also think about a kind of appendix with a presentation of different
> groupings. But that's not the first goal.

Well, I'd say let's go with the pydoc-based help system. As I said before,
it's one less thing we have to worry about maintaining/distributing. And
it's quite good, it will document everything that can be found in sys.path.
So as long as each individual module is well documented, the information
will be available to the users.

Remember that  pydoc has a fantastic web-server mode:

$  pydoc -p 7464 &

will run pydoc as a webserver on localhost:7464, with nice html docs for
everything in your sys.path. I use that constantly when developing, it's
beautiful.

We could stress that system's existence in the docs and make sure that each
module is itself well documented. In the long term, the issue of maintaing
separate manuals and in-module docstrings can be addressed. My preference is
having only lyx files  with all the docs as 'masters', and generating html,
PostScript, PDF, etc. from those (that's what I do for IPython). One could
make sure that at least the module top-level __doc__'s are set from the
masters and would thus get:

 - single-source manuals to be maintained, in LyX (or raw LaTeX)
 - multiple output formats from that source (html, PS, PDF).
 - module __doc__'s, accessible to pydoc for nice web browsing and the
builtin help system.

If you're interested, I have a simple wrapper around pdflatex and latex2html
called lyxport at http://www-hep.colorado.edu/~fperez/lyxport. I did it last
summer right before learning python, so it's in Perl :(. But hey, you don't
need to look inside, just use it :) It's convenient and works around some of
the annoyances of both latex2html and pdflatex.

> As I said, I think ipython would be the best interactive shell for
> scipy, also quite unbiased :-).

Hey, if it weren't for your IPP, IPython wouldn't exist at all. My initial
idea was a simple prompt system for python, nothing else. Only when I read
about your IPP did I realize much more could be done. And my original system
only used python's hooks (sys.displayhook, sys.ps1/2, etc.) which are nice
but ultimately limited. What got me going was seeing IPP's design based off
of the code.py module. After that, I wrote the tangled mess we have today.
So you have every right to be 'unbiased' about IPython :) I'm really glad
someone else is using it, since it was quite a bit of work.

Cheers,

f.

PS. Do you use lyx by any chance? I've been meaning to convert IPython's
docs to the standard Python howto layout, but I don't feel like making lyx
.layout files from the python latex styles. Since I know you've been working
on documentation issues, I was wondering. There's been talk in the lyx
mailing lists of writing those layout files but nobody seems to get around
to actually doing it (it's not hard, just a matter of overcoming the
startup inertia and having some time for it).