cython/cython — pull request #216 by nnemkin (2013-04-18 05:07:02+00:00)
Title: Autodoc improvements

Three improvements are included in this patch that I have found helpful when using Sphinx autodoc to document my project:

1) Default values preserve and display binary expressions and attribute access. For example, the following function will have its signature displayed as is:

cpdef func(int flags=MyModule.FLAG1 | MyModule.FLAG2)

This only affects expressions not reducible at compilation time, i.e. `2+2` will appear as `4`.

2) Public/readonly cdef attributes can have docstrings attached, using the [PEP 258 attribute docstring syntax](http://www.python.org/dev/peps/pep-0258/#attribute-docstrings). Example:

cdef class X:
cdef public attr
""""attr docstring"""

When ``embedsignature=True`` Cython already adds a signature docstring to the generated property (assuming the example above). This patch allows to add an actual docstring too.

Dosctrings on private cdef attributes will give a warning ("docstring ignored").
Other forms and uses of attribute docstrings, as described in the PEP 258, are not supported at all (SyntaxError), because there is no standard introspection mechanism designed for them. ([PEP 224](http://www.python.org/dev/peps/pep-0224/) describing such mechanism had been rejected.)

3) `bint` appears as `bool` (instead of `int`) in autogenerated signatures, as I suggested on the mailing list.

Each change is contained in its own commit in case you want to review them separately.