Re: Recommendations for documentation authors

From: René Ferdinand Rivera Morell (grafikrobot_at_[hidden])
Date: 2024-01-04 11:46:46

On Wed, Jan 3, 2024 at 10:25 AM Joel de Guzman via Boost
<boost_at_[hidden]> wrote:
> (* aside * René, I did not know you can write reference docs directly in
> the cpp source in Asciidoc. How do you do that?)

You use the region tagged inclusion
<https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regions/>.
It works similarly to the Quickbook snippets (which I used heavily and
extended and easily transitioned for asciidoctor). Some examples:

* B2: <https://github.com/bfgroup/b2/blob/main/src/engine/mod_jam_errors.h>,
rendered as <https://www.bfgroup.xyz/b2/manual/release/index.html#b2.reference.modules.errors>.
* Predef: <https://github.com/boostorg/predef/blob/develop/include/boost/predef/compiler/clang.h>,
rendered as <https://www.boost.org/doc/libs/1_84_0/libs/predef/doc/index.html#_boost_comp_clang>
* Lyra: <https://github.com/bfgroup/Lyra/blob/develop/include/lyra/opt.hpp>,
rendered as <https://www.bfgroup.xyz/Lyra/lyra.html#lyra_opt>

And a non-reference, but still code inclusion example..
<https://github.com/bfgroup/Lyra/blob/develop/examples/doc_groups.cpp>
rendered as <https://www.bfgroup.xyz/Lyra/lyra.html#_argument_groups>.
That mixes both including the doc and source code itself from the cpp
file with callouts in the code. And obviously the code is tested to
work in B2. So I know the examples are not accidentally broken.