[Cython] autodoc function/method signatures

[Dag Sverre Seljebotn]

Lisandro Dalcin wrote:
> I have some working code following Dag advices (BTW, that transform
> stuff its a real win!).  Now I would like to know your opinions about
> how the signatures should be rendered. Robert, if you see this, please
> enter the discussion.
>
>   

Great! Here's my opinions:

For coordination purposes I have now assigned this to you:
http://trac.cython.org/cython_trac/ticket/2
(If you haven't got a login there just send a .htpasswd file to Robert)

As for signatures, I think that whatever you do, it should be parseable 
by epydoc if possible. See the links Stefan put up under the ticket. 
This pretty much defines the format for non-typed code I think (i.e. if 
the type is "object" then don't specify the type, and Python-only syntax 
will look like Python..)

As for typed function signatures, I think just make it look like the 
Cython syntax, and whenever we actually support the "f(x: int)"-notation 
in Cython we can put in an option to support it in docstrings as well 
*shrug*. But an alternative is dropping the types I suppose (or making 
that part configurable; or even insert multiple lines with the first 
Python-only and the second explaining the types in prose).

(If you look at the top of runtests.py, you can plug in epydoc as an 
optional testing library, and make a regression test named 
"tests/run/epydoc_docstrings.pyx" which only runs if epydoc is installed 
on the system and call parse_function_signature in the testcase directly).

Dag Sverre