[Numpy-discussion] Extending documentation to c code

[David Goldsmith]

On Thu, May 27, 2010 at 9:18 AM, Charles R Harris <charlesr.harris at gmail.com
> wrote:

>
> On Wed, May 26, 2010 at 8:14 AM, Pauli Virtanen <pav at 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 at 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.
>

Thanks for being a voice for change! :-)


> 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.
>

And certainly at this early stage something is better than nothing.

DG

>
> Chuck
>
>
> _______________________________________________
> NumPy-Discussion mailing list
> NumPy-Discussion at scipy.org
> http://mail.scipy.org/mailman/listinfo/numpy-discussion
>
>


-- 
Mathematician: noun, someone who disavows certainty when their uncertainty
set is non-empty, even if that set has measure zero.

Hope: noun, that delusive spirit which escaped Pandora's jar and, with her
lies, prevents mankind from committing a general suicide.  (As interpreted
by Robert Graves)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20100527/65281664/attachment.html>