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

[Fernando Perez]

Matthew Brett wrote:

>>While I fully respect the opinion of those concerned about Travis' decision, I
>>have to say that I am personally not so worried.  At scipy'05, when Travis
>>announced the book idea, I asked a very simple question: 'are the docstrings
>>complete?'.  His answer was 'yes'.
>>
>>There was a good reason for my asking this question:  I personally find that
>>when coding, the most productive and efficient to learn a library is by typing
>>
>>import foo
>>foo.<TAB>
>>
>>and then
>>
>>foo.bar?
> 
> 
> Just a tiny addition.  I know what you mean, but my experience is of
> someone recently trying to learn numarray / Numeric, and I suspect I
> am not alone in printing out the documentation and reading a moderate
> amount of it before I get started.   Call me old-fashioned (it
> wouldn't be the first time!),

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.

Cheers,

f