[Numpy-discussion] Updated Numpy reference guide
Sun Aug 31 13:21:06 CDT 2008
I finished the first iteration of incorporating material from Travis
Oliphant's "Guide to Numpy" to the Sphinxy reference guide we were
constructing in the Doc marathon.
Result is here: (the PDF is a bit ugly, though, some content is almost
randomly scattered there)
Source is here: (Stéfan, if it looks ok to you, could you pull and check
if it builds for you when you have time?)
What I did with the "Guide to Numpy" material was:
- Collapsed each of the reference Chapters 3, 6, 8, 9 (ndarrays, scalars,
dtypes, ufuncs) with the more introductory material in Chapter 2.
- As this was supposed to be a reference guide, I tried to compress the
text from Chapter 2 as much as possible, by sticking to definitions and
dropping some more tutorial-oriented parts. This may have reduced
readability at some points...
- I added some small bits or rewrote parts in the above sections in
places where I thought it would improve the result.
- I did not include material that I thought was better to be put into
appropriate docstrings in Numpy.
What to do with class docstrings and obscure __xxx__ attributes was not
so clear a decision, so what I did for these varies.
- The sections about Ufuncs and array indexing are taken almost verbatim
from the "Guide to Numpy". The ndarray, scalar and dtype sections
somewhat follow the structure of the Guide, but the text is more heavily
edited from the original.
Some things to do:
- Descriptions about constructing items with __new__ methods should
probably still be clarified; I just replaced references to __new__ with
references to the corresponding classes.
- What to do with the material from numpy.doc.* should be decided, as the
text there doesn't look like it should go into a reference manual.
- Is this good enough to go into Numpy SVN at some point?
Or should we redo it and base the work closer to the original
"Guide to Numpy"?
- Does it build for you?
(I'd recommend using the development 0.5 version of Sphinx, so that you
get the nifty Inter-Sphinx links to the Python documentation.)
We are unfortunately beating the Sphinx with a big stick to make it
place the documentation of each function or class into a separate file,
and to convert the Numpy docstring format to something the Sphinx can
There's also some magic in place to make toctrees:: of function listings
more pleasant to the eye.
Any comments of what should be improved are welcome. (Even better: clone
the bzr branch, make the changes yourself, and put the result somewhere
available! E.g. as a bzr bundle or a branch on the launchpad.)
More information about the Numpy-discussion