[Matrix-SIG] Documentation for Numerical Python Extension writing

[Les Schaffer]

Travis says:
> I would appreciate feedback if you are interested in taking a look.

quick glance: definitely a start in the right direction.

what i would really like to see, especially with your aproach as
opposed to Konrad's slides, is to have (some of) this stuff go in the
darn SOURCE CODE!!!

NumPy is all about homogeneous arrays of numbers (etc). its about an
array object. we learn about array objects in arrayobject.h. lets go
see whats in arrayobject.h about array objects:

typedef struct {
  PyObject_HEAD
  char *data;
  int nd;
  int *dimensions, *strides;
  PyObject *base;
  PyArray_Descr *descr;
  int flags;
} PyArrayObject;

notice, not a comment in sight. 

even something as stupid as 

...
char * data; /* here's where the hallowed data lie.   */
             /* if you want access as array[i][j] see */
             /* PyArray_As2D below                    */
...

can lend sustenance to a poor wayfarer looking through the code for
the first time in preparation for doing a SWIG job to wrap array
objects from python into their <joke> 3D weather forecasting code
</joke>.

we can do better NumPy docs, as evidenced by travis' and konrad's
stuff. but doesnt some of this documentation belong IN THE SOURCE
CODE????? is there some way to accrete the acumulated wisdom of NumPy
users directly into the source, where many people who do numerical
work will ultimately look for guidance, consolation, spiritual values,
and entertainment. or how about an annotated HTML version of the numpy
code, with comments, URL links to other sites with examples of use of
particular pieces of the code (how DO I USE PyArray_As2D??????, oh
here's a way ...

arrayobject.h:
================
...
extern PyArray_Take_RET PyArray_Take PyArray_Take_PROTO;
extern PyArray_As1D_RET PyArray_As1D PyArray_As1D_PROTO;

/* 
this function lets you access 2D arrays in their rightful manner:
array[i][j].

URL:
http://www.docs.org/NumPy/PyArray_As2D/you_wont_believe_how_easy_it_is.html 
*/

extern PyArray_As2D_RET PyArray_As2D PyArray_As2D_PROTO;

....

i hereby offer time as in a few hours per week to help do something
like this, but only if its somehow officially tied in with NumPy so
the docs are current, accurate, timely, etc, and, um, uh,
official. nothing worse than a documenttaion branch and a source code
branch. 

les schaffer
-- 
____        Les Schaffer              ___| --->> Engineering R&D <<---
Theoretical & Applied Mechanics          |  Designspring, Inc. 
Center for Radiophysics & Space Research |  http://www.designspring.com/
Cornell Univ.  schaffer@tam.cornell.edu  |  les@designspring.com