[Numpy-discussion] Updated Numpy reference guide

[Pauli Virtanen]

Hi all,

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)

	http://www.iki.fi/pav/tmp/numpy-refguide/index.xhtml
	http://www.iki.fi/pav/tmp/numpy-refguide/NumPy.pdf

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?)

	https://code.launchpad.net/~pauli-virtanen/scipy/numpy-refguide

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.

Some questions:

- 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
  fathom.

  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.)

-- 
Pauli Virtanen