Re: Recommended way of generating documentation

From: pbristow_at_[hidden]
Date: 2020-01-06 17:28:56

> -----Original Message-----
> From: Boost <boost-bounces_at_[hidden]> On Behalf Of Richard Hodges via
> Boost
> Sent: 1 January 2020 12:03
> To: boost_at_[hidden] List <boost_at_[hidden]>
> Cc: Richard Hodges <hodges.r_at_[hidden]>
> Subject: Re: [boost] Recomended way of generating documentation
> 
> Treading carefully here as I'm new to boost library maintenance...
> 
> > So that you can cross-reference the Doxygen reference with whatever
> > other
> documentation you have
> 
> http://www.doxygen.nl/manual/autolink.html suggests that links to external
URLs
> are recognised by doxygen. Presumably linking to the correct place vis-a-vis
> release/developer builds can be controlled with a macro in a generated
Doxyfile?
> 
> > And it's Doxygen to XML, XML to Boostbook. Then of course Boostbook to
> Docbook, and Docbook to HTML.
> 
> Other than the very pleasing boost documentation styling, is this seemingly
> convoluted conversion route necessary? Is it not possible to configure a
Doxyfile to
> contain the correct styling?
> 
> I have no knowledge of the evolution of boost documentation and have no axe to
> grind, but as a newcomer it seems to me that there is a lot of 'unnecessary'
> compication in the production of documentation. I appreaciate that there's no
real
> sense in revisting existing libraries, but for new ones wouldn't it be prudent
to
> choose the shortest possible path which involves the least learning and
> maintenance?

It depends on the size of the documentation.

For 'trivial' documentation, the Doxygen and Markdown combination is acceptable,
but I believe strongly that the best Boost documentation is done using the
Quickbook toolchain (including Doxygen syntax comments to provide a references
section).

A killer feature of Quickbook is the ability to include code snippets from
actual C++ examples that can be run, ensuring that what you get is what compiles
and runs.

As a mark-up language Quickbook is pretty obvious (apart from the gotcha of
using indent-spaces  as a way to add code sections - a common but quick'n'dirty
markup feature that can cause some confusion).

Paul