[SciPy-user] [SciPy-dev] Re: [Numpy-discussion] Purchasing Documentation
Fernando.Perez at colorado.edu
Sun Oct 9 16:19:30 CDT 2005
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
> 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.
More information about the Numpy-discussion