Re: Exhale for Doxygen-generated API reference based on Sphinx

Subject: Re: Exhale for Doxygen-generated API reference based on Sphinx
From: Stefan Seefeld (stefan_at_[hidden])
Date: 2018-10-28 20:00:12

On 10/28/18 2:06 PM, Mateusz Loskot wrote:
> Hi,
>
> Thanks to Stefan, we now use Sphinx to generate the docs.
>
> Today, I was made aware of Exhale - Automatic C++ library API
> documentation generator using Doxygen, Sphinx, and Breathe.
> https://exhale.readthedocs.io/en/latest/index.html

Wow, this looks awesome !

> I have not looked into details how we generate docs now, but
> since we do use Sphinx, I thought the Exhale may be of our interest.
>
> Stefan, do you see any use for it, would it simplify anything
> or improve things, etc.?

I think it would indeed, yes ! The main issue we face with integrating
sphinx with doxygen are all the cross-links, notably from the tutorial
(written in RST and translated using sphinx) into the API reference
(generated using doxygen). Due to the lack of visibility from the former
into the latter, we hardcoded a number of links. This is brittle (the
links may stop working, either because a future version of doxygen
changes the internal structure of the docs, or because due to source
layout changes the references are no longer valid.

So, having a tighter integration will help: presumably it gives a
programmatic access to the doxygen-generated doc structure, so
references can be (re-)generated rather than hardcoded.

As a bonus, it would be great if we could use RST for inline docs in
C++, rather than doxygen-style markup, but that's a minor point and only
reflects my personal aesthetics. :-)

In short: I suggest we create a task in the issue tracker that captures
the first steps in adopting this tool, then hope someone will have the
time & motivation to pick it up.

Thanks,

Stefan

-- 
      ...ich hab' noch einen Koffer in Berlin...