[capi-sig] Documenting a C/Py API
barry at python.org
Mon Jul 2 19:12:40 CEST 2007
-----BEGIN PGP SIGNED MESSAGE-----
On Jul 2, 2007, at 9:30 AM, Campbell Barton wrote:
> 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.
This isn't necessarily true. In a previous life, I was doing tons of
C API stuff, essentially building and maintaining a big embedded/
extended Python application. We docstring'd all of our C API and
used epydoc to generate our API documentation. It worked very well,
with a few caveats.
First, epydoc had some problems in earlier versions, for example, the
fact that a class's docstring and its constructor's docstring both
live in the same slot in C. IIRC, epydoc also had some problems with
certain C inheritance style we were using, and a bunch of other minor
problems. AFAIK, these have mostly been addressed with newer epydoc
versions, though I honestly haven't looked at it for 6+ months.
Second, and more importantly, because of the nature of our app, we
had to run epydoc programmatically, inside the application's shell.
I think you're forced to use epydoc's import-based discovery
mechanisms when docstring'ing C code, so your modules have to be
importable. Because we were an embedded application, the package
namespace for our C code wasn't available except when the application
shell was run. Therefore we added a command line option that would
run the epydoc stuff, once Python was initialized and the extension
modules were available.
Other than that, we really didn't have to do much special to
docstring our C functions, provide them in normal Python interactive
interpreter help, and have nicely generated epydoc documentation.
All of our docstrings lived right in C and were attached to the C
functions using the normal Python C API structures.
I wish I could post some examples, but the code was closed-source and
the company no longer exists. ;)
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.7 (Darwin)
-----END PGP SIGNATURE-----
More information about the capi-sig