Ticket #2 (closed enhancement: fixed)

Opened 2 years ago

Last modified 21 months ago

Cython needs better support for API documentation

Reported by: robertwb Owned by: dalcinl@…
Priority: major Milestone: 0.10
Component: Packaging 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

Changed 2 years ago by robertwb

  • type changed from defect to enhancement

Changed 2 years ago by robertwb

  • owner changed from robertwb to somebody

Changed 2 years ago by robertwb

  • milestone set to wishlist

Changed 2 years ago 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

Changed 23 months ago by dagss

  • owner changed from somebody to dalcinl@…

Changed 23 months ago 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.

Changed 23 months ago by dagss

  • component changed from Packaging to Code Generation

Changed 23 months ago by dagss

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

Changed 22 months ago by robertwb

  • milestone changed from wishlist to 0.9.8.2

Changed 21 months ago by robertwb

  • component changed from Code Generation to Packaging
Note: See TracTickets for help on using tickets.