Auto generating C++ docs

[mpj]

Hi,

I was wondering if anyone has done any work on some kind of autoclass
equivalent for c++? I thought that using gccxml and pygccxml might be
an avenue worth exploring but I thought I'd check if anyone had put
some more thought into it.

Sphinx is ace, thank you for all the hard work.

Regards,
Michael

[Dan Craig]

+1

I'm looking to bring Sphinx into a C++ project that so far has been
documented (well, half heartedly) using Doxygen comments. I'd like to
somehow take advantage of that without having to re-write in rst.

On a more general note, are there any good examples of how to document
code in the API way? By that I mean point Sphinx to a directory of
source code and it builds documentation on each file, class, and
function? It looks like from the documentation that you have to
manually tell it what class/method/etc you want, but maybe I'm
confusing plain old references to code with the autodoc extension.

Dan

On Oct 22, 4:49 am, mpj <m.pricejo...@gmail.com> wrote:
> Hi,
>
> I was wondering if anyone has done any work on some kind of autoclass

> equivalent forc++? I thought that using gccxml and pygccxml might be

[Michael Jones]

To share what little research I've done, it seems that as gccxml is a
representation of the compilers internal state, comments are not
included in the output (having been ignored long ago by the compiler.)
However line numbers are included for the definitions so reparsing the
code for the comments is made significantly easier, especially as C++
is apparently notoriously hard to parse correctly.

Secondly, doxygen does a bit more than just display comments, so it'll
take a fair bit of effort before anything comparable is created. It is
possible that some kind of doxygen-sphinx bridge might be a more
productive extension.

I'm tempted to start looking at it but I've not found the time.

Cheers,
Michael

[Dan Craig]

Doxygen does have an XML output, so that seems like the first place to
start. Perhaps the solution would be to autogenerate the rst source
for Sphinx. Run Doxygen to generate XML, then run a DoxyXML-rst
converter that populates a folder in the Sphinx source. Maybe that
could be called by a directive. Something like:

:: doxygen-rst /path/to/Doxyfile

There are probably more parameters needed, but you get the idea.

On Dec 5, 5:48 am, "Michael Jones" <m.pricejo...@gmail.com> wrote:
> To share what little research I've done, it seems that as gccxml is a
> representation of the compilers internal state, comments are not
> included in the output (having been ignored long ago by the compiler.)
> However line numbers are included for the definitions so reparsing the
> code for the comments is made significantly easier, especially as C++
> is apparently notoriously hard to parse correctly.
>
> Secondly, doxygen does a bit more than just display comments, so it'll
> take a fair bit of effort before anything comparable is created. It is
> possible that some kind of doxygen-sphinx bridge might be a more
> productive extension.
>
> I'm tempted to start looking at it but I've not found the time.
>
> Cheers,
> Michael
>

[Dmitriy]

Hi, Michael (and the rest of the Sphinx mailing list),

Have you had any luck with this? I would be very interested in using
Sphinx to document C++ code.

Thanks.
Dmitriy

[Dmitriy]

Hi, Michael (and the rest of the Sphinx mailing list),

Have you had any luck with this? I would be very interested in using
Sphinx to document C++ code.

Thanks.
Dmitriy

On Oct 22, 1:49 am, mpj <m.pricejo...@gmail.com> wrote:

[Michael Jones]

I've not tried, though I believe Dan's suggestion to be the best
direction to go in, with the one problem that the Doxygen XML output
is still in development so might well be subject to change.

I'm still not finding the time I'm afraid.

Michael

[Michael Jones]

I'm giving this a whirl, I'll keep this thread updated with progress.
Might not be anything of interest before the new year though. Give us
a shout if you'd like to help out,

Michael

[Dmitriy Morozov]

I'd like to help out. In particular, I'm curous how you are
approaching this. Do you intend to go with Doxygen, or something else
(there are some nice tools out there like pygccxml and synopsis)? It
would be nice to do this in a decoupled fashion: if the directives for
C++ could be decoupled from the actual parser, then plugging different
ways of extracting documentation out of C++ comments would be easier.

Dmitriy

[Michael Jones]

For those interested, I've not made much progress, what I have done is
summarised by the following two repositories:

Sphinx extension:
http://github.com/michaeljones/breathe/tree/master

Output processing:
http://github.com/michaeljones/doxml/tree/master

I'm getting into a rhythm of working on it, but it might still be
several weeks before something basic is in place.

Michael

[rodrigob]

I'm currently working on the documentation of a large C++ project
using Sphinx (Doxygen is just not readable enough...).

I was initially planning to do a trick like
http://www.vlfeat.org/api/index.html

where they split a generated page to use a header and footer for the
generated doxygen html pages.

However the 'breathe' extensions seems to be a better way of doing
things.

Could you explain the status of the project ?
Do you think it is a viable option ?
Is it somewhere a sample of the expected output ?

Retrieving the current git branch and running the testsuite today
provides an

>>>>
breathe/testsuite$ make html
mkdir -p build/html build/doctrees
sphinx-build -b html -a -N -d build/doctrees source build/html
Extension error:
Could not import extension breathe (exception: No module named
indexsuper)
<<<<

And it seems that indexsuper
http://google.com/codesearch?hl=en&sa=N&q=indexsuper++lang:python&ct=rr&cs_r=lang:python

is supposed to be provided by your code ?


Thanks for your answer.
Regards,
rodrigob.

On Feb 8, 1:09 pm, Michael Jones <m.pricejo...@gmail.com> wrote:
> For those interested, I've not made much progress, what I have done is
> summarised by the following two repositories:
>
> Sphinx extension:http://github.com/michaeljones/breathe/tree/master
>
> Output processing:http://github.com/michaeljones/doxml/tree/master
>
> I'm getting into a rhythm of working on it, but it might still be
> several weeks before something basic is in place.
>
> Michael
>

> On Mon, Dec 15, 2008 at 11:02 PM, Michael Jones <m.pricejo...@gmail.com> wrote:
> > I'm giving this a whirl, I'll keep this thread updated with progress.
> > Might not be anything of interest before the new year though. Give us
> > a shout if you'd like to help out,
>
> > Michael
>

[Michael Jones]

Thanks for taking the time to check it out, sorry I didn't leave it in
a working state. I've not worked on it for a bit as I was taking time
out to work on another extension and get used to the rst/Sphinx setup.

It is next on my list so I'll get back to it next week. The first
thing I'll do is get it in a state where it actually runs!

From what I remember it currently reads in the information from the
index.xml file of the doxygen xml output and displays that in a very
basic format but does not yet move on to extracting the details from
the other referenced xml files.

For more direct answers to your questions:
- The project is in early development stage.
- I think it will be a viable option but some issues need to be
overcome like how to easily generating multiple pages without having
to be too explicit in the mark up.
- There is no example of the final expected output, I'm not sure
enough of the systems involved to know fully what to expect.

Cheers,
Michael

[rodrigo benenson]

Thanks for the answer ! I guess I'm not the only one expecting to look
the results of this effort.
If you have specific issues I may be able to help you (I do write code
in a daily basis and have some experience writing python
applications).
I'm curious to see how much "better than plain Doxygen" we can get...

Regards,
rodrigob.

[Michael Jones]

Making some progress. Still not exactly production ready but it is a
solid start.

Latest results at:
http://michaeljones.github.com/breathe/tinyxml.html

Feedback, requests, direction always welcome. One problem I have is a
lack of code to test with (all my C++ work is proprietary stuff so
best not to up load it to the net) if anyone has some examples they
can donate to the repository that would be sweet. Especially if it has
features you would like supported sooner rather than later.

I've also created:
http://github.com/michaeljones/sphinx-to-github/tree/master

To help get sphinx output up on to github pages.

Cheers,
Michael


On Fri, Mar 20, 2009 at 7:34 PM, Michael Jones <m.pric...@gmail.com> wrote:
> I've updated the readme file in the repository to properly describe
> how to get the testsuite running. I warn you though the result is
> pretty ugly!
>
> Cheers for the offer of help. At the moment the main issue is just
> thinking through the design properly. I'll try working on a spec to
> flesh out the approach but you are more than welcome to contribute in
> any way you like.
>
> Michael