Re: Google Season of Docs

From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2020-04-20 20:52:12

On Mon, Apr 20, 2020 at 3:38 PM Glen Fernandes via Boost <
boost_at_[hidden]> wrote:

> On Mon, Apr 20, 2020 at 1:59 PM Hans Dembinski <hans.dembinski_at_[hidden]>
> wrote:
> > My main question: I generate my reference with doxygen in xml. The xml
> code is then post-
> > processed using a Python script. The result is then integrated into my
> Quickbook docs(*) I
> > quickly checked Jamfiles for the example libraries you mentioned, and
> none of those seem to
> > have a doxygen-generated reference. How would I combine doxygen and
> Asciidoc?
>
> [...]
>
> > (*) How much annoyed I am by the inability of doxygen to produce a
> proper reference for a
> > template-heavy lib like Boost.Histogram is another story, but I really
> don't want to write the
> > reference by hand either and keep it in sync with code changes manually.
>
> I don't have a solution for that, I'm afraid. As you've found, all of
> the above have reference documentation manually written. (I stopped
> using Doxygen even when Quickbook/Boostbook was involved, though so I
> never invested time in finding out how to make things work with
> Doxygen)
>

My long standing solution is to move the manual reference documentation as
close as possible to the code itself. For example Predef uses asciidoctor
and has a reference section. Which is embedded in the source code...

Reference.. <
https://www.boost.org/doc/libs/develop/libs/predef/doc/index.html#_reference
>
Doc source.. <
https://github.com/boostorg/predef/blob/develop/include/boost/predef/compiler/clang.h#L14
>

-- 
-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net