Hi Pauli! On Sun, Aug 31, 2008 at 8:21 PM, Pauli Virtanen <[EMAIL PROTECTED]> wrote: > > 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.) I think it looks excellent. It'd be cool if all the docs could finally be at one place, instead of scattered all over the wiki. So for me, any form in sphinx is ok. Ondrej _______________________________________________ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
