Annoucing robin, a new Doxygen to Sphinx bridge

[Anteru]

Hi,

We're happy to announce robin, a new Doxygen/C++ to Sphinx bridge. Robin
provides an easy-to-use, easy-to-hack integration of Doxygen
documentation into Sphinx. Robin is licensed under the BSD and can be
found at Bitbucket: https://bitbucket.org/reima/robin

Features
========

* Robust extraction of Doxygen XML data via an easy-to-hack parser
* Intermediate data is stored in a database (mongodb) for simple
extraction and processing
* Directive-driven output; each directive provides callbacks and hooks
which allows for deep customization
* Automated generation of driver ReST documents: Similar to automodule;
however, robin generates actual ReST documents which can be inspected

Prerequisites
=============

Robin expects a running mongodb on the local host. It uses a minimal set
of external libraries: Pymongo, sphinx, progressbar. All of the
dependencies can be easily installed using pip or easy_install.

Robin has been developed with Python 2.7; we have not tested previous
versions.

Getting started
===============

* Run Doxygen to generate XML documentation (GENERATE_XML=YES)
* Run extract-doxygen <path to XML> <project name>
* Run create-rst <project name>
This generates several directories (classes, groups, etc.)
Include the groups.rst into your toc
* Add 'robin.sphinx' to the Sphinx extensions
* Build (make html) for TOC update
* Build again (make clean && make html)

Status
======

We're using robin internally for a large C++ codebase, and there are a
few minor issues left that we hope to resolve soon (all of them are
tracked on Bitbucket.) After that, we expect that robin will go into
"maintenance" mode focusing on bug fixes only. If someone is interested
in contributing, please get in touch with us.

Cheers,
the robin developers

[dleach]

Folks,

I see that you have added a "hello world" type of example. In the doc directory there is an XML directory that is already populated. Where did this come from? Is this output from Doxygen that you have decided to add to the example?



On Friday, June 29, 2012 12:49:33 PM UTC-5, dleach wrote:

I'm giving this a try but I'm slightly confused. I'm new to both Doxygen and Sphinx but I've been able to create content for both. Now I'm trying to settle on using Sphinx throughout my project and use some tool to bridge Doxygen content to the Sphinx world. I've tried breathe and then ran across this tool.

Does this tool support files section yet?

It would be useful if the example included a bit more stuff like file .c/.cpp/.h stuff and some sort of simple "hello world" type of program... maybe even start with c/cpp code as the example with the doxygen configuration file so that the users can go end to end on the process (run doxygen, then run your tools...).

[Anteru]

Yes, the XML stuff is the Doxygen output. You can get it with
GENERATE_XML set to YES in your Doxyfile.

[David Leach]

A minor suggestion then. From a project perspective, you probably wouldn't want to check in to your source archive something that is the output of a process (like running doxygen). I would think you would have a documentation build process that would make a doxygen pass over your code base to generate the intermediate files before running the make via sphinx.

At least this is what I'm trying to do with a large project I have that is using a mix of languages (C, C++, python, etc)... Hence my interest in this tool.

[Anteru]

Hi,

we've added the generated files to the repository so you can run it out
of the box instead of downloading TinyXML and having to run doxygen on
it. Moreover, with a different Doxygen version than we used (1.8.1),
things might get broken. This is for the sake of simplicity, in a real
world use case you would of course generate the Doxygen XML first.

Did the example help? Could you get it running?

Cheers

[dleach]

Yes I did try it and it basically worked.

But I do have a question, in your announcement you indicated that your project was a large C++ project. My project is C based and I find that most of the docxygen strings are in my C modules instead of the header files. But your bridge tool doesn't seem to extract from there? Am I missing something?

[Anteru]

We didn't test with C projects at all. However, we also have nearly all
documentation in the .cpp files and not in the headers. Robin doesn't
actually care about that at all, as long as doxygen correctly finds the
documentation. Check your XML output if everything is included there.
Just run doxygen as usual, if you see it in the HTML output, then it
should be also present in the XML.

If the stuff is documented there, but not in robin, feel free to file a bug.

Cheers

> <newsg...@catchall.shelter13.net

> --
> You received this message because you are subscribed to the Google
> Groups "sphinx-dev" group.
> To view this discussion on the web visit
> https://groups.google.com/d/msg/sphinx-dev/-/rUgHB1m-BeMJ.
> To post to this group, send email to sphin...@googlegroups.com.
> To unsubscribe from this group, send email to
> sphinx-dev+...@googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/sphinx-dev?hl=en.

[Michael Jones]

Hey,

I wrote Breathe, if you'd be up for providing a short explanation of
why you started your project and what advantages you feel your
approach has then I'd love to put it in the Breathe readme so that
people can see alternatives.

Cheers,
Michael

> --
> You received this message because you are subscribed to the Google Groups "sphinx-dev" group.

[Anteru]

Hi,

we did try Breathe actually; the main problem we had with it was that we
couldn't hack the output easily and that there was no "automodule"
support in it to generate documentation for all files in a project. Our
goal was to make a minimal bridge which is easy to hack, so anything
that is missing can be added easily, and to abstract away from Doxygen
as quickly as possible.

There's still some stuff which can be implemented better in Robin (for
instance, we currently need two passes over the generated .rst files)
but our feeling is that hacking Robin to get it working will be easier
than hacking Breathe. If you take a look at Robin, it's cleanly
separated into one pass which converts from Doxygen to MongoDB, and a
second pass which works on well-structured data. We did actually a split
on the development side, with one author writing each of the parts :)

That's however our personal view, and so far, we do generate the
documentation for a large C++ project with it and we're happy. If
there's anything we can do to make the code more accessible, feel free
to drop us a line.

Cheers

Am 28.08.2012 22:51, schrieb Michael Gielda:
> Hi,
>
> My thoughts exactly, Michael, I use your Breathe extension and most of
> the stuff just works... gotta test if the new thing provides more
> functionality but perhaps the authors can point us in the right direction?
> I mean Breathe is not ideal but perhaps it would be wiser to fill in the
> blanks than write a new framework from scratch. Still, if it is there,
> perhaps they can benefit mutually from the 'competition'?
>
> Best,
> Michael (it's a fairly popular name ;) )

> <javascript:>.

> > To unsubscribe from this group, send email to

> sphinx-dev+...@googlegroups.com <javascript:>.

> > For more options, visit this group at
> http://groups.google.com/group/sphinx-dev?hl=en

> <http://groups.google.com/group/sphinx-dev?hl=en>.

> >
>
> --
> You received this message because you are subscribed to the Google
> Groups "sphinx-dev" group.

> To view this discussion on the web visit

> https://groups.google.com/d/msg/sphinx-dev/-/7Xgdn5bp2hQJ.

[Michael Gielda]

Hi Anteru,

Firstly, a big thanks for answering in such detail, it is nice to have a good understanding of your intentions and motivations :)

I think that yours is a bit different of a use case than ours and in a sense I can see that you may need a different project for that kind of stuff.

We are using breathe for a mixed language project, but to be able to illustrate uses with examples etc. rather than providing full documentation, at least at the moment.

For doing 'fully automatic' stuff we just use Doxygen - it can generate neat stuff if you (and especially your customers) need it. I think Sphinx is not meant for such things anyway, I mean it would be nice to be able to do that, why not, but good Sphinx docs can't be automatic, they need the human attention. Though I do remember forcing breathe to generate docs for an entire class, so doing a whole project should not be so terrible if you had to. 

What is for me a downside of your solution is the mongodb - one more service you need to run, one more thing that can break :)

Still, congratulations on an ambitious project and for contributing it to the community - and under BSD, nice!

Best,

Michael