Re: [boost] Recommendations for documentation authors

On 1/4/24 7:46 PM, René Ferdinand Rivera Morell wrote:

On Wed, Jan 3, 2024 at 10:25 AM Joel de Guzman via Boost 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-regio.... 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.er.... * Predef: https://github.com/boostorg/predef/blob/develop/include/boost/predef/compile..., rendered as https://www.boost.org/doc/libs/1_84_0/libs/predef/doc/index.html#_boost_comp... * 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.

Sweet! Just what I need. Thanks! Cheers, -- Joel de Guzman