[SciPy-user] [SciPy-dev] Re: [Numpy-discussion] Purchasing Documentation

[Tim Churches]

Fernando Perez wrote:
> Certainly.  As I said, I do think there is room for 'book-style' (as
> opposed to API reference) books for scipy.  Langtangen's ($$$) and
> Perry's (free) are two such existing offers, and now Travis' comes in as
> well (and I still believe there is room for more).
> 
> My idea was of top-level (module) docstrings which would provide a
> reasonable overview, along with single-function ones providing not only
> API reference but also a few examples.  Since pydoc -w can generate
> permanent HTML for browsing/printing out of any module (and docutils has
> even more sophisticated facilities), I think this provides acceptable
> coverage of the basic library. And it does give anyone who wants
> 'material to read on the bus' (which I often need myself) a reasonable
> solution, I think.
> 
> I just wanted to clarify that a docstring-based set of docs is not
> limited either to interactive usage via ipython, nor to raw API
> information.  It can both be printed for offline use, and can cover
> enough overview and examples to be genuinely useful standalone.  Not a
> substitute for a full book, but not a crippled tool either, I think.

Sounds like the ideal solution to me. Now, I wonder if it is possible to
resolve the legal situation over the existing NumPy documentation? By
which I mean, I wonder if it is possible to just copy suitable parts of
the NumPy docs into the scipy.core docstrings (improving on them if
possible) - with attribution of course. Or is it necessary or safer to
start from scratch, or at least to extensively paraphrase the NumPy docs?

Finally, to whom should we send docstrings? To Travis?

Tim C