Re: Google Season of Docs

From: pbristow_at_[hidden]
Date: 2020-04-23 10:54:40

> -----Original Message-----
> From: Boost <boost-bounces_at_[hidden]> On Behalf Of Cem Bassoy via Boost
> Sent: 23 April 2020 11:36
> To: boost_at_[hidden]
> Cc: Cem Bassoy <cem.bassoy_at_[hidden]>
> Subject: Re: [boost] Google Season of Docs
> 
> Am Do., 23. Apr. 2020 um 11:54 Uhr schrieb Alexander Grund via Boost <
> boost_at_[hidden]>:
> 
> >
> > >> maintainers to agree in a single tech to document anything.
> > > Definitely.  No chance.
> > >
> > > Almost every library has 'done their own thing' in various way,
> > > either
> > by using
> > > a different tool, or by using an existing tool differently.
> > FWIW: I'd welcome something more standard. Like:
> > You want Doxygen: Use this setup (Jamfile/CMakeLists) You want
> > Asciidoc: Use that
> > BoostBook?: Here you go
> >
> 
> I guess that this topic would not be the scope of GSoD.
> However, I think you will find good examples for each approach in the Boost
> libraries.
> 
> 
> >
> > I know there is no "one size fits all", but maybe a "use this for
> > code-heavy and that for template heavy libraries."
> >
> 
> > Or just any guideline. I was a bit lost when I added the documentation
> > for Nowide. I didn't want to install 3 or 4 different tools and go
> > through 3 conversions just to get some docu done. Especially not if B2
> > magic is involved which can't be easily replicated in (e.g.) CMake
> >
> 
> This is the crux of the story. If it is so complicated to integrate such a
toolchain or
> multiple tools, you are automatically thinking about the "pain" of
using/linking and
> maintaing them.
> Ultimately, the degree of necessity and urgency determines the course of
action -
> the willingness to integrate a hard-to-maintain-toolchain.
> 
> If I think that Doxygen is not an ultimate necessity for my library and I am
using
> AsciiDoc, I might want to postpone Doxygen-usage and the maintainance of a
more
> complicated toolchain If it a big necessity for my library, I might want to
switch to
> Sphinx with exhale/breathe additions including doxygen or search for or
> implement an addtional tool that can combine AsciiDoc with Doxygen.
> 
> So, IMO, we do not need a howto for that as the howtos are already there (I
agree
> sometimes also hard to find).
> With different libraries and requirements, time will show a convergence -
maybe
> with multiple convergence points.
> I am not sure if there is a greatest common factor and if we can get something
like
> a common look for all libraries.
> 
> Are their parts of the Boost library documentation which could be
> restructured/renewed - not directly affecting the libraries?

I started a demo project on producing Quickbook/Doxygen docs, but more important
things meant that it was pushed on the stack, and then, after stack overflow, it
was 'lost'.

My demo was good enough for simple libraries, but we haven't solved the
complications from meta-magic - and most new libraries make use of these
features.

But I fear that this boat has sailed... ?

Paul