Hi all,
I would like to explore auto-gen documentation tools (similar to Doxygen). Does anyone know of such, besides: Dosygen, Sphinx, hdoc, QDoc, MkDocs?
1 Like
I’m not aware of any other major ones. I think they all have their pros and cons and all integrate fairly well with CI and Github Pages. Oddly enough, the only one I’m not too familiar with is QDoc even though I work with Qt professionally.
I haven’t tried this, but it exists:
1 Like
Also:
I think most people still use doxygen for parsing, including clang. It’s ugly, but parsing C++ is hard. Consequently, I think sometimes people use doxygen to parse and the sphinx breathe plugin for prettier rendering.
Bottom line, don’t expect a perfect solution right now.
I think we’re overdue for a revisitation of doc generation tech, though. I have this theory that projects using the CMake FILE_SET Headers feature should be able to have a nearly zero configuration doxygen experience (i.e., no Doxyfile or Makefile), but I won’t have time to personally implement that for a while.
For mp-units v0.8.0, I tried the doxygen + breathe + sphinx pipeline. It was a nightmare. Each tool crashed and failed to parse C++20 code. I strongly discourage such an approach.
If we were about to parse the code to autogenic the documentation, it would be a solution for the “API Reference” part. It would not replace the handwritten “User Manual.” For the Beman Project, we would look for a toolchain that would generate docs in a standards-like manner. I tried to do this here: API Reference - mp-units.
There is also GitHub - standardese/standardese: A (work-in-progress) nextgen Doxygen for C++, but Jonathan is no longer maintaining it and personally discouraged me from using it for mp-units.
Hyde is what we use for stlab libraries. It parses headers to verify out-of-line documentation is up-to-date. +CC @sean-parent
1 Like