[Numpy-discussion] packaging scipy (was Re: Simple financial functions for NumPy)

[Gael Varoquaux]

On Tue, Apr 08, 2008 at 06:15:25AM -0600, Steven H. Rogers wrote:
> At the IPython Sprint in Boulder last year Fernando suggested that 
> someone look at this issue.  I've given it some thought and started a 
> wiki page for it.  Inputs would be welcome and might motivate me to find 
> the time to implement something.

> http://ipython.scipy.org/moin/Developer_Zone/SearchDocs

A huge progress has been made in the direction of solving this problem
with the release of sphinx (http://sphinx.pocoo.org/). This is a
documentation-generation tool that creates html docs from restructured
text. The docs are really nice, but a very interesting feature is that
they have a "search" page, which works with javascript code on the
client: no need for a server.

For documenting Mayavi, I generated a function reference from the
docstrings. It is very easy using the inspect module. Then I used my
homebrewed rst comiler to build the docs. I plan to replace this with
sphinx very soon. This will give us ability to search the docstrings and
the full docs (dostrings cannot replace a user manual).

Ipython and sympy have also decided to go the sphinx way. In fact Ondrej
has already converted the ipython1 docs to sphinx, you can check them out
on:


http://ipython.scipy.org/doc/ipython1/html/
http://ipython.scipy.org/doc/ipython1/ipython1.pdf

Sphinx seems a very promising to the everlasting problem of documentation.

Cheers,

Gaël