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

Subject: Re: Exhale for Doxygen-generated API reference based on Sphinx
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2018-10-30 21:00:09

On Sun, 28 Oct 2018 at 21:00, Stefan Seefeld <stefan_at_[hidden]> wrote:
> On 10/28/18 2:06 PM, Mateusz Loskot wrote:
> >
> > 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).

Yes, I think those are not easy to achieve.
I'm not even sure if Boost.Geometry, which uses custom XML-based
parser  does that.

> 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. :-)

I agree with your personal aesthetics :-)
RST or Markdown would be better than Doxygen, I guess.

Take the current gil/concepts.hpp, section COLOR BASE CONCEPTS
This whole prose does not belong there.
It is very hard to maintain such source code interleaved with big chunks
of commentary, where the commentary itself is full of C++ code...
I wish we could move those into accompanying .rst or .md files and
integrate with tooling.

> 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.

Whoever tries the Exhale first, opens the issue :)
Meanwhile, I'd also point out there two generators which offer interesting
features, both are clang-based:

https://github.com/foonathan/standardese
https://github.com/jessevdk/cldoc

where the first one seems most intersting to me.

It does offer a miniml set of custom markup, but AFAIU, none is required
It also supports "Inside the comment you can use arbitrary* Markdown*
in the documentation comments and it will be rendered appropriately.
It uses Markdown links format.

To summary:
- given the current use of Sphinx+Doxygen, we need to look at Exhale indeed
- if we consider dropping use of Doxygen, then standardese seems worth checking

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net