[SciPy-Dev] documenting scipy.special functions

josef.pktd@gmai... josef.pktd@gmai...
Sat Aug 6 03:12:51 CDT 2011

This came up in https://github.com/scipy/scipy/pull/52

One more comment about scipy.special docstrings: From what I have seen
they are semiautomatically created. I think eventually we should
switch to docstrings following the numpy standard. There are several
functions where I would have liked to add more information. The
current docstrings of many special functions are awfully uninformative
about details.

As for the comments...that's actually not as simple as it sounds. Or
at least it wasn't. I just submitted a pull request to numpy to help
change that. ufuncs are python objects whose docstrings are read-only.
They are set at object creation. The either (1)must be passed in to
the C function creating the ufunc (at which point you have to have the
docs in some C header file or parse them in from a Python header file
with the docs), or (2) you must reset what the ufunc doc pointer
points to at the C level. The add_newdoc method doesn't work on
ufuncs. (And in fact there are a number of calls to add_newdoc in
numpy/add_newdocs.py that don't change the documentation. It isn't
noticed because add_newdoc specifically catches all errors and does

Is it possible to improve the docstring for the scipy.special
functions (in the long run)?

I'm just a consumer of scipy.special, but every once in a while I
would like to add some information to special functions.

for some it looks possible to edit (and bring them to numpy standard),
e.g. http://docs.scipy.org/scipy/docs/scipy.special.orthogonal.hermite/#hermite

others, for example
http://docs.scipy.org/scipy/docs/scipy.special._cephes.pdtr/#pdtr ,
cannot be edited, but there is a lot of information hidden in the
fortran files, if one looks for it long enough.


More information about the SciPy-Dev mailing list