Travis's response is below (he is the main numpy author). He is very enthusiastic about the addition of docstrings with examples to numpy.
------- Forwarded message ------- From: "Travis Oliphant" <[EMAIL PROTECTED]> To: "William Stein" <[EMAIL PROTECTED]> Cc: Subject: Re: numpy in SAGE, etc. Date: Wed, 06 Dec 2006 09:58:43 -0800 > > (1) The file numpy/add_newdocs.py in the numpy distribution > defines somehow docstrings for a lot of the numpy constructors. > A SAGE developer could simply add tons of examples to this file, > based on playing around, and reading the numpy book to learn what > is relevant to illustrate. As each numpy distribution is > released, we would *merge* this file with the one in the new > numpy distribution (e.g., very easily using Mercurial). > > (2) You might think it would be possible to change the docstrings > at runtime, but I think they may be hardcoded in (many are for > code defined in extension classes). The point of add_newdocs and the functions it calls is to add doc-strings to functions and methods defined in extension modules without having to re-compile (and to be able to use Python for defining the long strings). So, yes, it is very possible to significantly enhance the docstrings. > > And finally, am I just wrong -- would Travis, etc., want these > docstrings with tons of examples? Travis -- since I cc'd you, > maybe you can just answer. Absolutely we want more docstrings and examples. The only reason they are not there is that nobody has done it. I've made it very easy even for extension modules using the add_newdocs approach, but I've simply been swamped. > > So evidently the scipy people have for some reason not even decided > on a format for their documentation, which is partly why they don't > have it. For the record, in SAGE there is a very precise documentation > format that is systematically and uniformly applied throughout the > system: > > * We liberally use latex in the docstrings. I wrote a Python > function > that preparses this to make it human readable, when one types > foo? > > * The format of each docstring is as follows: > function header > """ > 1-2 sentences summarizing what the function does. > > INPUT: > var1 -- type, defaults, what it is > var2 -- ... > OUTPUT: > description of output var or vars (if tuple) > > EXAMPLES: > a *bunch* of examples, often a whole page. > > NOTES: > misc other notes > > ALGORITHM: > notes about the implementation or algorithm, if applicable > > AUTHORS: > -- name (date): notes about what was done > """ > > The INPUT and OUTPUT blocks are typeset as a latex verbatim > environment. The rest is typeset using normal latex. > It's good to use the itemize environment when necessary > for lists, also. > > Essentially all the documtation in SAGE has exactly this format. > VERY often I rewrite documentation for code people send me so > that it is formated as above. (So if you send me code, please > format it exactly as above!!!) > > The SAGE reference manual is autogenerated from the source code > using a script I wrote that basically extracts the documentation > (mainly using Python introspection), and puts it in the same format > as the standard Python documentation suite, then runs the standard > Python documentation tools on it. Note, however, that the > structure of the reference manual is laid out by hand (i.e., order > of chapters, some heading text, etc.), which is I think very important. > This sounds great. Please share :-) > I suggest scipy consider a similar strategy. This sounds fine. The reason that there is not a consistent standard is that nobody has championed it. The whole problem is that SciPy has pretty much been run by Eric, Pearu, and me. Eric has been very busy with his company over the past couple of years. Pearu has checked in and out over the past year (I think he got married), and I re-wrote NumPy and so have not been able to spend the time on SciPy that it deserves. The SciPy world has received lots of new volunteers, but so far nobody has been willing to write documentation consistently. Another minor part of the problem is that Pearu and I are both happy with and fond of LaTeX (actually I use LyX as a front end). But Eric pretty much doesn't like it and so he has been (mildly) pushing Word (he begrudgingly accepted the idea that LyX could be a way to write docs). There are a few other resistant people who don't seem to want to use "LaTeX" in the docstrings and keep looking for some other way to do it. Perhaps with your enthusiasm (and already written tools to process them) we could finally push things into the direction you are describing. > "Successfully installed scipy-2006-12-05 > Now cleaning up tmp files." > > on my MacBookPro, after installing the new Intel fortran compiler. Cool. Very good to know. -Travis --~--~---------~--~----~------------~-------~--~----~ To post to this group, send email to [email protected] To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/sage-devel URLs: http://sage.scipy.org/sage/ and http://modular.math.washington.edu/sage/ -~----------~----~----~----~------~----~------~--~---
