ENH: use __text_signature__ if pydoc.doc does not reveal a signature.

[MSeifert04]

This allows to support the __text_signature__ property on Python 3.4+ to document C functions.

I had a problem since I started my project: I could either support IPython autocompletion for parameters or use numpydoc and have the signature.

Say, I have a C Function with a docstring:

"foo(x, y)\n\
\n\
actual docs"

IPython isn't able to parse a Signature because inspect.Signature just doesn't know what to do with it. numpydoc and sphinx however document it correctly.

If I change it to

"foo(x, y)\n\
--\n\
\n\
actual docs"

IPython and inspect.Signature do work. But they seem to remove it from the docstring. Therefore numpydoc (probably even sphinx itself) can't document the signature from pydoc.getdoc.

Accessing the __text_signature__ solves this problem! I locally get correctly rendered signatures AND IPythons autocompletion. No idea if it breaks something else, at least my project now renders correctly.

[MSeifert04]

Does anyone want to review my PR?

[rgommers]

Looks good to me. Works as expected, and builds the SciPy docs fine. So merging. Thanks @MSeifert04