[SciPy-user] [SciPy-dev] Re: [Numpy-discussion] Purchasing Documentation

[Arnd Baecker]

On Thu, 6 Oct 2005, Fernando Perez wrote:

[...]

> To reiterate before my reputation is tarnished forever: the bet was with John,
> who is the doughnuts-eating one.  Being a man of taste, I eat bagels :) [and I
> wasn't present when the bet was made]
>
> With that critical point out of the way, on to minor details.

Thanks for the clarification - this definitively made my day ;-)

[...]
> In fact, I'd like docstrings to provide (simple) examples in them,

+(some large positive number ;-)

> and one thing on my radar now that
> ipython is growing GUI/XML legs is to add support for latex in docstrings.

Are you thinking of restructured text
  http://docutils.sourceforge.net/
together with the mathhack
  http://docutils.sourceforge.net/sandbox/cben/rolehack/
or the tools used in the LaTeXwiki,
  http://mcelrath.org/Notes/LatexWiki
?

Independent of this, I see two main points:
- how should the examples be added
- who should add the examples
to the doc-strings?
Getting "end-users" to help with this task sounds quite attractive to me.

Would it make sense to revive the pynotes idea
http://www.scipy.org/documentation/mailman?fn=scipy-dev/2004-November/002536.html
which would make it possible to add remarks to any python command?

However, I don't know if there is a good solution on how to
submit these notes and how they finally
should get merged into the doc-string
(One possibility would be to combine this in some way
with Travis' live-docs).
It might be unavoidable that at the end some knowledgable person has
to go over suggested additions and incorporate them
on a case-by-case basis?

Best,

Arnd