[SciPy-dev] Fwd: [sage-devel] numpy in SAGE, etc.

[Gary Ruben]

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.