[SciPy-dev] Callback arguments in Sphinx Documentation

Ralf Gommers ralf.gommers@googlemail....
Thu Aug 27 22:42:03 CDT 2009


On Thu, Aug 27, 2009 at 4:07 AM, John Salvatier
<jsalvati@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@scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/scipy-dev/attachments/20090827/0213f75e/attachment.html 


More information about the Scipy-dev mailing list