Re: [boost] Google Season of Docs

Dear Glen,

On 20. Apr 2020, at 17:18, Glen Fernandes via Boost 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.