[capi-sig] Documenting a C/Py API
e-huss at netmeridian.com
Tue Jul 3 23:54:43 CEST 2007
> In Blender3D were doing an API refactor and Im looking at better ways to
> write the Python C/API documentation.
> At the moment we use epydoc, Its all Iv used so I don't have much to
> compare it to.
> If you havnt used it, its basically a way to add formatting to your
> normal .py docstrings so they can be converted into HTML or PDF.
> This works well with python only projects but is not somthing you can do
> in C without some manual docstring extraction from the C/API.
I use epydoc extensively, with a lot of C code. Actually, a lot of it is
Pyrex, so it's much easier to write and is more natural, but the basics
should be the same.
The latest versions of epydoc are much better. I would suggest getting
the latest straight from subversion, it is pretty stable.
I think Barry may have mentioned this, but you can put __init__ signatures
in the type docstring. I haven't experimented with this, much. This
isn't completely documented, you can look in epydoc/docstringparser.py and
look for SIGNATURE_RE. See this message from some detail:
I have one of my projects up where you can look at the docs generated by
epydoc. The majority of this code is in Pyrex:
More information about the capi-sig