Re: Google Season of Docs

From: Hans Dembinski (hans.dembinski_at_[hidden])
Date: 2020-04-20 17:59:40

Dear Glen,

> On 20. Apr 2020, at 17:18, Glen Fernandes via Boost <boost_at_[hidden]> wrote:
> 
> On Mon, Apr 20, 2020 at 5:11 AM Cem Bassoy wrote:
>> 
>> Mateusz Loskot wrote:
>> 
>>> Cem Bassoy wrote:
>>>> 
>>>> Is GIL using AsciiDoc?
>>> 
>>> No, GIL is using reStructuredText and Sphinx,
>>> but if I was migrating today, I'd go for AsciiDoc, I think.
>> 
>> Can you shortly elaborate? I am asking for ublas.
> 
> If you're interested, we've converted a few Boost library
> documentation from HTML to Asciidoc. For example:
> 
> - Boost.Endian:
>        Now: https://www.boost.org/doc/libs/1_72_0/libs/endian/doc/html/endian.html
>        Before: https://www.boost.org/doc/libs/1_70_0/libs/endian/doc/index.html
> 
> - Boost.IO:
>        Now: https://www.boost.org/doc/libs/master/libs/io/doc/html/io.html
>        Before: https://www.boost.org/doc/libs/1_72_0/libs/io/doc/index.html
> 
> - Boost.Smart_Ptr:
>        Now: https://www.boost.org/doc/libs/1_72_0/libs/smart_ptr/doc/html/smart_ptr.html
>        Before:
> https://www.boost.org/doc/libs/1_64_0/libs/smart_ptr/smart_ptr.htm
> 
> The Asciidoc files and Jamfiles involved in these projects (and others
> - e.g. Boost.Mp11, Boost.Variant2, Boost.Assert, Boost.System are all
> Asciidoc too) should highlight how straightforward this would be if
> you choose to adopt it. The asciidoctor tool is also fairly easy to
> run for users to generate this documentation themselves, compared to
> Quickbook+Boostbook. I'm told it is simpler and easier to run than
> Sphinx too.

thank you mentioning this. I am interested in switching from Quickbook to Asciidoc. I am mostly ok with Quickbook, but it is bothering me very much that I am required to close my sections with [endsect]. That is machine-friendly and not human-friendly. I also like the style for the Asciidoc docs with the TOC on the left.

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?

Best regards,
Hans

(*) 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.