Re: Google Season of Docs

From: Glen Fernandes (glen.fernandes_at_[hidden])
Date: 2020-04-20 15:18:59

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.

Glen