Re: Google Season of Docs

From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2020-04-20 15:37:38

On Mon, 20 Apr 2020 at 17:19, 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.
> [...]
> 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 Glen.

Cem, my first issue with Sphinx is reST which, and Quickbook too,
I find not as friendly for a human reader as I do find AsciiDoc.
I like Markdown and AsciiDoc feels more like it and offers
semantic features that I'm missing from Markdown.
I also find Python legacies in Sphinx a bit itching
- originally developed for Python, ported to other domains,
while AsciiDoc and its tools feel domain-agnostic.

OTOH, some argue Sphinx is more capable than AsciiDoctor
here I found a good summary, may be outdated though
https://github.com/neovim/neovim/issues/329#issuecomment-56082074

There are some interesting tools for AsciiDoc format, e.g. http://antora.org/

Finally, as Glen explained, some Boost libraries selected AsciiDoc,
so it makes sense to me to follow the crowd to be able to share knowledge
and any tools and infrastructure that appears in future.

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net