[Matrix-SIG] Documentation for Numerical Python Extension writing

[Konrad Hinsen]

> Well, it looks like two of us have been working on explaining how to write
> the extensions in C using the arrayobject specific calls.

Better two than nobody!

> Here is the link:
> http://oliphant.netpedia.net/packages/Numerical_Extensions.ps.gz

Looks... ugly. Hardly readable in fact. Do I need some Lyx-specific
TeX macro packages to get a decent result? For the moment the best
way to read it is reading the LaTeX source directly.

The contents, however, are much better! And I hope that you will
continue with the ufunc stuff, about which I know nothing, but which
could be very useful for some projects.

It's also worthwhile to have a decent description of how to use SWIG
typemaps. I have never used this either, but I could imagine that
in many cases it is the simplest solution.

> I would appreciate feedback if you are interested in taking a look.  My
> approach is a little different than Konrad's in that it is less tutorial
> in nature as it trys to document all of the calls.  It exposes all of the
> API even though a typical user would not use all of the calls.

Which raises an important question. I did not attempt to document the
full C API for three reasons: 1) laziness (the main one) 2) in order
not to intimidate new users 3) because I don't know how much is
considered "official", in the sense of supported in future releases.

Of course there should be a reference guide in addition to a tutorial,
but the question of what will be the "official" C API remains to be
answered. Some functions in NumPy seem of little use to end users, so
it's better not to consider them official, to keep more freedom for
future improvements. Other functions are hard to understand and/or
buggy; the borderline is unclear. Perhaps the best approach is to
divide a reference manual into "official" and "known to work, but
perhaps not forever" sections.

-- 
-------------------------------------------------------------------------------
Konrad Hinsen                            | E-Mail: hinsen@cnrs-orleans.fr
Centre de Biophysique Moleculaire (CNRS) | Tel.: +33-2.38.25.55.69
Rue Charles Sadron                       | Fax:  +33-2.38.63.15.17
45071 Orleans Cedex 2                    | Deutsch/Esperanto/English/
France                                   | Nederlands/Francais
-------------------------------------------------------------------------------