[Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008

Joe Harrington jh@physics.ucf....
Sat May 17 13:29:48 CDT 2008


> I didn't see Travis's Numpy book mentioned at all in your writeup, so
> I am wondering where its role in the doc effort is.

> Is it OK to copy material out of the book and into 
> other parts of the documentation?

No worries, Travis is on board here.  We included him and others on
the Steering Committee in planning this effort.

Travis's book overlaps the current effort to some extent.  The
function descriptions in the book are the numpy docstrings, such as
they currently exist.  The docstrings are open source software and the
book is a work derived from them.  The current effort is essentially
to fill in the docstrings to the full expectation of professional
reference documentation.  If you compare the docstring example on the
wiki (for multivariate_normal) with the current page for that
function, you'll see the difference.  The multivariate_normal
docstring is actually pretty good among current docstrings, but even
for this function we're aiming for a big change.  Collected, the new
docstrings will make a reference manual very much like those you'll
find for other scientific languages, with similar format for the
pages.  The choice of a ReST-based docstring format some time ago was
to support producing such a manual.

The rest of Travis's book is still critical information and we're not
contemplating replacing it at this point.  Much of it is on the
technical end, and our goal is to address the general user,
particularly students learning to do data analysis, so I think even
the eventual User Guide, whatever form it takes, will not encroach on
its technical focus.  Of course, he's welcome to include the improved
docstrings in his book if he wants to (as is anyone), or to exclude
them and make a tighter book aimed at extension programmers, or
whatever.

Let's continue discussion on scipy-dev, just to keep it all in one
place.

--jh--


More information about the Numpy-discussion mailing list