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?
Just my experience with current documentation workflow. If I got anything wrong: See it as exemplary how confusing it is ;)
Alex
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost