[SciPy-dev] Callback arguments in Sphinx Documentation

[Ralf Gommers]

On Thu, Aug 27, 2009 at 4:07 AM, John Salvatier
<jsalvati at u.washington.edu>wrote:

> Hello all,
>
> I am writing the Documentation for scikits.bvp_solver using Sphinx.
>
> bvp_solver uses a lot of relatively complex callback arguments, so I am
> looking for a good way to document their format. Nesting ".. method::"
> directives does not seem to work. Does anyone have any ideas about how to
> document the signatures of callback arguments elegantly; has anyone dealt
> with this before?


For numpy/scipy docs the signature is either contained in the type
description (like
http://docs.scipy.org/numpy/docs/numpy.lib.function_base.piecewise ) or just
given in words (like
http://docs.scipy.org/scipy/docs/scipy.integrate.quadpack.tplquad ).

It works because the signatures are usually simple, but there's certainly
room for improvement. Keep in mind though that your solution will have to
work for text terminals as well as with Sphinx, which is not so easy.
..method:: directives would look bad in a text terminal even if they did
work.

Cheers,
Ralf


>
>
> Best Regards,
> John Salvatier
>
> _______________________________________________
> Scipy-dev mailing list
> Scipy-dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20090827/0213f75e/attachment.html>