Re: Google Season of Docs

From: Cem Bassoy (cem.bassoy_at_[hidden])
Date: 2020-04-20 20:23:26

Am Mo., 20. Apr. 2020 um 17:19 Uhr schrieb Glen Fernandes <
glen.fernandes_at_[hidden]>:

> 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
>