Re: [sphinx-dev] Annoucing robin, a new Doxygen to Sphinx bridge
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 ;) ) On Sunday, 26 August 2012 00:18:01 UTC+2, mpj wrote: 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 On Sat, Jun 16, 2012 at 3:59 AM, Anteru newsg...@catchall.shelter13.net javascript: wrote: 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 -- You received this message because you are subscribed to the Google Groups sphinx-dev group. To post to this group, send email to sphin...@googlegroups.comjavascript:. 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. -- 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. To post to this group, send email to sphinx-dev@googlegroups.com. To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.
Re: [sphinx-dev] Annoucing robin, a new Doxygen to Sphinx bridge
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 ;) ) On Sunday, 26 August 2012 00:18:01 UTC+2, mpj wrote: 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 On Sat, Jun 16, 2012 at 3:59 AM, Anteru newsg...@catchall.shelter13.net javascript: wrote: 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 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 -- You received this message because you are subscribed to the Google Groups sphinx-dev group. To post to this group, send email to sphin...@googlegroups.com 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. To post to this group, send email to sphinx-dev@googlegroups.com. To unsubscribe from this group, send email to
Re: [sphinx-dev] Annoucing robin, a new Doxygen to Sphinx bridge
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
On Saturday, 1 September 2012 21:15:07 UTC+2, Anteru wrote:
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 ;) )
On Sunday, 26 August 2012 00:18:01 UTC+2, mpj wrote:
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
On Sat, Jun 16, 2012 at 3:59 AM, Anteru
newsg...@catchall.shelter13.net javascript: wrote:
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
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.)
Re: [sphinx-dev] Annoucing robin, a new Doxygen to Sphinx bridge
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 On Sat, Jun 16, 2012 at 3:59 AM, Anteru newsgro...@catchall.shelter13.net wrote: 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 -- You received this message because you are subscribed to the Google Groups sphinx-dev group. To post to this group, send email to sphinx-dev@googlegroups.com. To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.com. For more options, visit this group at 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 post to this group, send email to sphinx-dev@googlegroups.com. To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.
