[Cython] generating documentation from Cython source code (was: [cython-users] Compiling a Cython module *without* having the required libraries)

[Stefan Behnel]

Nikolaj van Omme schrieb am 28.06.2015 um 21:02:
> On 15-06-28 02:52 PM, Stefan Behnel wrote:
>> Nathann Cohen schrieb am 28.06.2015 um 18:44:
>>>> Could you generate Python stub modules for them by grepping out def/cpdef
>>>> functions and extension types together with their docstrings from the
>>>> Cython sources?
>>> Would there be a not-so-awful way to do this parsing?
>>>
>>> We may have classes and methods inside. Possibly several layers of it
>>> (sorry, I know >_<).
>> Well, the *right* way would let Cython do the parsing and integrate it with
>> Sphinx, maybe via a Sphinx plugin. Either Cython could generate Python
>> stubs (should be easy to do, see e.g. Cython/CodeWriter.py), or it could
>> write out some XML/JSON/whatever representation of the source code metadata
>> that other tools could use for further processing.
>>
>> The Python stub approach has the advantage of supporting normal Python
>> tools, a dedicated file format has the advantage of allowing a more
>> complete representation of the source code metadata.
>>
>> Both would be nice to have, I guess. But for the purpose of generating API
>> documentation, Python stubs should get you most of the way already without
>> requiring plugins for all documentation tools. Signature types could still
>> be represented by mapping them to Python annotations (with a "# type:
>> ignore" marker to disable PEP 484 type checks...).
> 
> We are facing the same issues. Maybe we could team up and work on a
> solution together?

Please do. :)

Can we move further discussion to the cython-devel mailing list?

Stefan