Re: Recommended way of generating documentation

classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view
|

Re: Recommended way of generating documentation

Boost - Dev mailing list


> -----Original Message-----
> From: Boost <[hidden email]> On Behalf Of Richard Hodges via
> Boost
> Sent: 1 January 2020 12:03
> To: [hidden email] List <[hidden email]>
> Cc: Richard Hodges <[hidden email]>
> 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







_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost