[Pyrex] Documenting Pyrex modules

[Stefan Behnel]

Hi,

I've been looking for a way to make Pyrex modules more accessible from Python.
What they currently support as C-classes is docstrings, so you can write
method and class documentation into a docstring and have it read by help() etc.

However, since Pyrex is a translator and code generator already, it would be
nice if it could add some more semantics to the generated module API or if it
could interface with tools like pythondoc or epydoc to document the API.

One thing I could think of would be automatic adding of a signature
description, as things like keyword parameters are not visible in
C-implemented classes. Another thing would be the selective output of an API
description à la pythondoc (which uses a simple XML format), as Pyrex knows
which parameters there are, which types are expected, which type is returned
(and /if/ there actually is a return statement), etc. This is much more than
is actually visible through Python's reflection (which is what pyrexdoc does).

So there is a lot of semantics that Pyrex could expose to external
documentation tools. Before I start thinking about this in any further depth,
has anyone already thought about this? Any ideas where to start or opinions
which tool to target?

Stefan