[Numpy-discussion] docs.scipy.org -- new site for the documentation marathon

[Jarrod Millman]

On Sun, Oct 26, 2008 at 9:41 AM, Nathan Bell <wnbell at gmail.com> wrote:
> As a concrete example of your question, I've been working on some
> scipy.sparse documentation [1], and it seems like it will be fairly
> lengthy when completed.  Would it be appropriate to merge it into the
> Sphinx documentation for scipy.sparse [2], or should the Sphinx docs
> be more concise?
>
> [1] http://www.scipy.org/SciPyPackages/Sparse
> [2] http://docs.scipy.org/doc/scipy/reference/sparse.html

Thanks Nathan for working on the sparse documentation!  I would like
to see all your documentation in the Sphinx docs:
http://docs.scipy.org/doc/scipy/reference/sparse.htm

All the documentation should be in the Sphinx system.  One of the main
advantages of using the Sphinx system is that it is much easier to
make living documentation if it is more closely integrated with the
code.  First, when changes are made to the code it is much easier to
just use a tool like grep or grin to find all the places where you
need to update the documentation.  Since we can use matplotlib to
generate figures when the documentation is created, we can better
ensure that the figures in our documentation can be generated by the
code in our documentation.  We can also use our testing infrastructure
to run any code in the documentation.  This has the advantages of
providing us with more tests and helps keep code in our documentation
runnable.

I would like to see http://www.scipy.org/SciPyPackages/Sparse removed
and all the content merged into
http://docs.scipy.org/doc/scipy/reference/sparse.html

I have cross-posted my response to the numpy list, but let's have this
discussion on the scipy developer's list going forward.

Thanks,

-- 
Jarrod Millman
Computational Infrastructure for Research Labs
10 Giannini Hall, UC Berkeley
phone: 510.643.4014
http://cirl.berkeley.edu/