Cython needs better support for API documentation

[robertwb]

Currently, Python functions and methods in Cython generated C modules cannot provide their signature to interactive introspection. This is a major problem for the "help()" function in the interpreter (where function signatures look like "parse(...)"), but also to API doc generation tools like epydoc.

epydoc supports a special first line in the docstring here that mimics the look of the signature:

 http://epydoc.sourceforge.net/api/epydoc.docstringparser-module.html#parse_function_signature  http://epydoc.sourceforge.net/api/epydoc.docstringparser-pysrc.html#parse_function_signature

Cython could generate such a line based on the original source signature.

[Stefan Behnel]

On the mailing list, Dag Seljebotn provided an idea how to implement this.

 http://permalink.gmane.org/gmane.comp.python.cython.devel/2830

[dagss]

The main work is now done by Lisandro Dalcin:  http://hg.cython.org/cython-devel/rev/075511424c24

There's still a problem with formatting of some types, notably all ints are displayed as int and buffers etc. aren't displayed at all.

In order to remedy this, the transform should be moved to after AnalyseDeclarations so that parsed PyrexType objects can be queried for their description, however then one should factor out how cpdef creates a def-node into a post-analysis transform so that copying the doc isn't necesarry.

[dagss]

 http://article.gmane.org/gmane.comp.python.cython.devel/2937  http://hg.cython.org/cython-devel/rev/d115fd6ed2df