Campbell Barton <cbarton@metavr.com> writes:
Ideally Id like to only maintain 1 set of docs... so possibilities are [...]
If you maintain only one set of docs, then your options are indeed limited. I tend to agree with Carsten that docstrings and full documentation are in fact different; docstrings tend to be briefer, don't provide examples, and in fact don't have real formatting. Attempts to add HTML-like formatting to docstrings lead to them not being readable from Python, which defeats the purpose. The Python source is a precedent for maintaining two sets of documentation and for the distinction between them.
We currently document the C-implemented classes with Doxygen by writing dummy classes with markup that Doxygen understands. The line numbers are off and Doxygen doesn't understand some Python features (and tries to shoehorn others into C++ terminology), but other than that, it serves us well. We haven't tried epydoc yet.