Re: [boost] Google Season of Docs

-----Original Message----- From: Boost On Behalf Of Cem Bassoy via Boost Sent: 23 April 2020 11:36 To: boost@lists.boost.org Cc: Cem Bassoy Subject: Re: [boost] Google Season of Docs

Am Do., 23. Apr. 2020 um 11:54 Uhr schrieb Alexander Grund via Boost < boost@lists.boost.org>:

...

...

...

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