cmake-init
cmake-init copied to clipboard
friendlyanon
Doxygen 1.9 can't be used to run `docs`
Because of m.css not having still support for Doxygen 1.9 the cmake --build --preset=dev -t docs fails with a weird message, maybe adding a detailed error saying to downgrade Doxygen to 1.8 or switching to another frontend that supports doxygen 1.9
Yes, the situation around docs isn't the prettiest right now. Also mentioned in https://github.com/friendlyanon/cmake-init/issues/41#issuecomment-1004035454 I would be happy with an alternative solution.
Might be a dumb question to ask, but why do you use m.css in the first place? If it's causing trouble and is on the edge of being abandonware why not use vanilla Doxygen instead? In the end, m.css is just a skin that (significantly) improves Doxygen's visual appearance but it also brings in an unnecessary (?) sketchy dependency. I understand that the intention of this repository is to be opinionated but reverting to good old vanilla Doxygen would not rip out too much functionality and users are still free to throw in their own custom skins: https://doxygen.nl/manual/customize.html
My suggestion: separate the discussion about possible Doxygen replacements from the question whether m.css is a good skin, e.g., by splitting the label doxygen into two labels: doxygen and m.css.
The default Doxygen skin is really not good and as you answered your own question, it significantly improves the quality of the output. Having one less thing to setup in an initializer utility is a good thing.
As mentioned in https://github.com/friendlyanon/cmake-init/issues/58, I would be happy to move to alternatives as well. If you think you can improve things in this area, PRs are also welcome. I have a bit less time nowadays to do a lot of extra research in this area.
Well, my suggestion is to get rid of m.css but I fully appreciate different opinions about that; but I will not bother to make PRs if you had reasons to choose m.css and would decline the PR anyhow. AFAIK, you are not losing any features (besides visual appearance) by abandoning m.css. However, these doxygen issues are not genuine Doxygen problems but m.css issues and for the sake of transparency, you should rename this label.
m.css also provides a quick search that I really really like. It's a small thing, but it's gives that polished feel and makes looking for things much easier. Check the m.css demo: https://doc.magnum.graphics/magnum/
In fact, I'm going to mention it separately here that I really don't like how cppreference removed their own search feature and instead co-opted to use DDG. You used to get a small popup that showed you results as you typed. I think it's a real issue that now you get redirected to get search results. My insistence in this regard probably reflects this annoyance of mine.
Thinking about this issue a bit longer I think that the current solution is actually fine. From a user perspective, it is easier to remove m.css and to fall back to vanilla Doxygen than to include it post hoc.
I'm using doxygen-awesome-css (example) for one of my libs and I quite like it. Not sure if it suits your purpose, but it's worth a look!
Works fine with Doxygen 1.9.6.
