Ticket #2 (closed enhancement: fixed)

Opened 7 months ago

Last modified 2 weeks ago

Cython needs better support for API documentation

Reported by: robertwb Assigned to: dalcinl@gmail.com
Priority: major Milestone: 0.10
Component: Packaging Version:
Keywords: Cc:

Description

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.

Change History

05/05/2008 05:13:35 PM changed by robertwb

  • type changed from defect to enhancement.

05/05/2008 05:23:31 PM changed by robertwb

  • owner changed from robertwb to somebody.

08/18/2008 08:56:27 PM changed by robertwb

  • milestone set to wishlist.

09/05/2008 01:33:32 AM changed by 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

09/08/2008 08:12:09 AM changed by dagss

  • owner changed from somebody to dalcinl@gmail.com.

09/19/2008 07:34:13 AM changed by 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.

09/19/2008 07:43:25 AM changed by dagss

  • component changed from Packaging to Code Generation.

09/24/2008 07:54:37 AM changed by dagss

  • status changed from new to closed.
  • resolution set to fixed.

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

10/08/2008 12:15:26 AM changed by robertwb

  • milestone changed from wishlist to 0.9.8.2.

11/08/2008 03:34:54 PM changed by robertwb

  • component changed from Code Generation to Packaging.