Hi Guys, 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. http://www.blender.org/documentation/244PythonDoc/index.html
Ideally Id like to only maintain 1 set of docs... so possibilities are them as HTML still)
- dont write epydocs, only use docstrings (we need a way we can browse
dont write C API/docstrings, just have empty strings where all the docstrings would go.
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.
Cheers