Suggestions for documentation generation?

[kpd]

Hello,

I have written a C++ library that I've then wrapped with Pyrex.
Any suggestions to the best-in-class tool to create documentation for
the libraries?

I would love to document things in one spot (could be the code) and
generate html and PDF from there.

Doxygen (www.doxygen.org) looks to be about the best so far.

Thanks,

[John M. Gabriele]

kpd wrote:

Hello,

I have written a C++ library that I've then wrapped with Pyrex.
Any suggestions to the best-in-class tool to create documentation for
the libraries?

I would love to document things in one spot (could be the code) and
generate html and PDF from there.

Doxygen (www.doxygen.org) looks to be about the best so far.

Thanks,

I've heard that some folks use pythondoc:
http://starship.python.net/crew/danilo/pythondoc/
http://effbot.org/zone/pythondoc.htm

There's also HappyDoc http://happydoc.sourceforge.net/
and EpyDoc http://epydoc.sourceforge.net/ .

--
(remove zeez if demunging email address)

[Terry Hancock]

On Wed, 01 Mar 2006 19:58:50 -0500
"John M. Gabriele" <jo************@yahooz.com> wrote:

kpd wrote:

I have written a C++ library that I've then wrapped with
Pyrex. Any suggestions to the best-in-class tool to
create documentation for the libraries?

I would love to document things in one spot (could be
the code) and generate html and PDF from there.

Doxygen (www.doxygen.org) looks to be about the best so
far.

I've heard that some folks use pythondoc:
http://starship.python.net/crew/danilo/pythondoc/
http://effbot.org/zone/pythondoc.htm

There's also HappyDoc http://happydoc.sourceforge.net/
and EpyDoc http://epydoc.sourceforge.net/ .

Those are great, but I don't think they handle C++ ;-)

Which makes me wonder -- will epydoc work on a pyrex or
C-extension file if it defines the __doc__ strings?

--
Terry Hancock (ha*****@AnansiSpaceworks.com)
Anansi Spaceworks http://www.AnansiSpaceworks.com

[kpd]

Thanks - I took at both. Also at 'percepts', which I used a long time
ago (had forgotten about it). Percepts has a great little java applet
for viewing the class hierarchy. I don't think it works for python,
just C++ though. Looks like doxygen will fit the bill.

[Michael Ekstrand]

On 2 Mar 2006 04:06:17 -0800
"kpd" <ke**************@gmail.com> wrote:

Thanks - I took at both. Also at 'percepts', which I used a long time
ago (had forgotten about it). Percepts has a great little java applet
for viewing the class hierarchy. I don't think it works for python,
just C++ though. Looks like doxygen will fit the bill.

An excellent choice IMHO.

Doxygen has recently added support for Python, so if there is
pure-Python code interfacing with the rest of your work, that can be
documented also.

- Michael

--
mouse, n: a device for pointing at the xterm in which you want to type.
-- Fortune

[John M. Gabriele]

Michael Ekstrand wrote:

Doxygen has recently added support for Python, [snip]

Didn't know that. Thanks for the heads-up. :)

--
(remove zeez if demunging email address)

[Bo Peng]

kpd wrote:

Hello,

I have written a C++ library that I've then wrapped with Pyrex.
Any suggestions to the best-in-class tool to create documentation for
the libraries?

I would love to document things in one spot (could be the code) and
generate html and PDF from there.

Doxygen (www.doxygen.org) looks to be about the best so far.

I was facing the same problem and took the following approach:

1. write c++ code with doxygen-complaint comments
2. generate XML comments using doxygen
3. parse XML and generate Python docstring
4. insert the docstring into SWIG interface file

I can send you the parser but I do not know if pyrex support python
docstring.

Bo