[capi-sig] Documenting a C/Py API
cbarton at metavr.com
Mon Jul 2 15:30:57 CEST 2007
first post on the list, dont be shy ;)
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.
for blender3d we have C doctrings as well as python files that just
contain functions with docstrings (no actual code) for epydoc to write
them to html.
The C/API docstings often end up being brief and not that helpful, since
the epydocs are what most people use so more effort is put there.
Here are the current epydocs.
Ideally Id like to only maintain 1 set of docs... so possibilities are
1) dont write epydocs, only use docstrings (we need a way we can browse
them as HTML still)
2) dont write C API/docstrings, just have empty strings where all the
docstrings would go.
3) include epydoc formatting in C API/docstrings and pass these
docstrings to epydoc for it to generate HTML.
Iv got 3) working as a testcase, the message attached details how this
works with the pro's and con's of adding epydoc tags into C/API docstrings.
However Id be interested to know how other projects deal with the issue
of maintaining docstrings and online docs.
More information about the capi-sig