[SciPy-user] Sparse matrix usage, documentation.

[Fernando Perez]

On 5/13/06, Ed Schofield <schofield at ftw.at> wrote:
> Neilen Marais wrote:
> > Hi
> >
> > The documentation for the sparse matrix classes seem to be, well, sparse.
> > Does documentation exist somewhere I'm missing, or is it simply to early
> > in the development process for much documentation to be around? I may be
> > able to commit some once I understand what's going on though :)
> >
> I've just added some basic documentation to SVN, accessible from the
> prompt with help(sparse).  I'd be very grateful if you could contribute
> any more examples.  Do you think it should take the form of a wiki page,
> or as an html or pdf file in the source tree?

Regardless of how it gets documented, I'd suggest getting into the habit of:

a) Having at least usable docstrings.  Docstrings are the 'first line
of defense' for finding out about libraries, they are the standard
python documenting tool, they get picked up by automatic API
generation tools (pydoc being the most basic of the lot), etc.  In
addition, I know many of us (though I'm obviously biased) to a lot of
library-discovery-by-tab-and-?-key in ipython.

The combination of tabbing my way around a module, along with
modname.foo*? and modname.foo_what_I_want? can really zoom in
surprisingly quickly into the relevant information, if a library has
sensible names and decent docstrings.

b) If further information is put on HTML/wiki/PDF formats, I'd suggest
having at the end of the relevant dosctrings, something like:

For further details, see:
http://scipy.org/apidocs/somelib/foo.html
http://scipy.org/apidocs/somelib/foo_complete.pdf

It would be trivial for future GUI-based environments to parse
docstrings for url-looking strings and make them available on a
browser.  In fact, even today, gnome's terminal already makes such
strings into hyperlinks automatically, which you can open by
right-clicking on them (a menu pops up with 'open link' as an option).

Just a suggestion.

Cheers,

f

ps - Obviously this is the tip of the iceberg, but I don't want to get
started on a long disucssion of documentation standards, example
inclusion, special __www__ attributes, etc.