I suspect William is right about the lack of a standard format hindering the documentation. I hope something like his format can be adopted. I'd also specify some way of delineating examples so that they can be preprocessed and run as part of the unit tests. SAGE uses matplotlib and it's currently a de facto standard. Could it be adopted in examples somehow, with any preprocessor perhaps skipping examples which contained visual examples or modifying them to suppress plot windows appearing? Maybe a standard way to provide references to example code outside a docstring should also be defined so that examples covering multiple functions can be referenced from several places. I suspect this sort of thing would require breaking away from the standard docstring idea. As I've mentioned previously, this would also allow doing things like running the example code interactively. Another thing that William's email doesn't cover is non-function documentation; it might be worth defining a similar documentation format for numpy classes and types. Finally, should the NOTES: section be used for "see also" tags or should a SEE ALSO: section be added? Gary R. <snip>
(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).
OK, so I don't have many options. Thoughts? Does anybody want to help? Any person who wants to learn numpy could probably easily write these examples along the way. Instead of just learning numpy, you could more systematically learn numpy and at the same time contribute tons of useful doctests.
<snip>
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.