Am Mo., 20. Apr. 2020 um 17:19 Uhr schrieb Glen Fernandes < glen.fernandes@gmail.com>:
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.orgsciidoc files and Jamfiles involved in these projects (a/doc/libs/1_72_0/libs/smart_ptr/doc/html/smart_ptr.html 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.
I had a little bit of experience with sphinx using exhale and breathe. The output generation with the Jamfile seems to be simpler than with Sphinx. Is there a possibility to integrate doxygen reference like with sphinx using exhale and breathe? One could add an extra section for the reference hmtl, but only in the doxygen style. Maybe using an external converter. However, I haven't seen a reference section for Boost.IO/Boost.Endian/etc. (not needed?) Thanks, Cem
Glen