On Wed, May 26, 2010 at 8:14 AM, Pauli Virtanen <pav@iki.fi> wrote:

Wed, 26 May 2010 07:15:08 -0600, Charles R Harris wrote:
> On Wed, May 26, 2010 at 2:59 AM, Pauli Virtanen <pav@iki.fi> wrote:
>
>> Wed, 26 May 2010 06:57:27 +0900, David Cournapeau wrote: [clip:
>> doxygen]
>> > It is yet another format to use inside C sources (I don't think
>> > doxygen supports rest), and I would rather have something that is
>> > similar, ideally integrated into sphinx. It also generates rather
>> > ugly doc by default,
>>
>> Anyway, we can probably nevertheless just agree on a readable
>> plain-text/ rst format, and then just use doxygen to generate the docs,
>> as a band-aid.
>>
>> http://github.com/pv/numpycdoc
>
> Neat. I didn't quite see the how how you connected the rst documentation
> and doxygen.

I didn't :)

But I just did: doing this it was actually a 10 min job since Doxygen
accepts HTML -- now it parses the comments as RST and renders it properly
as HTML in the Doxygen output. Of course getting links etc. to work would
require more effort, but that's left as an exercise for someone else to
finish.

Why don't you go ahead and merge this. If someone wants to substitute something else for doxygen at some point, then that is still open, meanwhile we can get started on writing some cdocs. In particular, it would be nice if the folks doing the code refactoring also documented any new functions. We can also put together a numpycdoc standard to go with it. I think your idea of combining the standard numpy doc format with the usual c code comment style is the way to go.

Chuck