externl
commented
7 months ago While I don't disagree with these changes in general, I'm not a fan of trying to manage patches to this is css theme. Whenever we want to update it from the latest upstream it would more than likely be a pain. Maybe we can open an issue with them to improve their css.
I think we all agree this theme is an overall improvement over the current Doxygen theme, but I think there are some things that could be improved, or that used to be better.
1) Reduce vertical padding between elements
For an API reference, I think information density is important, and right now the sheet amount of vertical padding between elements looks extreme, and hurts the density. For example, some of the worst offenders are simple lists of items:
Without the theming, we can fit twice as many elements on a single page. And I still find that list perfectly readable.
But I find this a problem in general, not just for lists. Comparing the Glacier2 module reference: https://doc.zeroc.com/api/ice/main/slice/namespaceGlacier2.html https://doc.zeroc.com/api/ice/3.7/slice/namespaceGlacier2.html The non-styled version fits everything on a single page. The styled version only fits 3/4 of the content on a page. For an API reference, the more I can fit on my screen, the better! (Especially when I'm checking every page to see what else Doxygen broke...)
2) Make the pages full-width
The new theme limits pages to a fixed-width column for tablets (I'm guessing). This can hurt information density like the first point, but has a tangibly negative effect on things that hit that width limit.
Even some medium-length function signatures and descriptions get line wrapped, which makes them harder to read.
And some of our larger images now get scaled down, which messes them up, and also makes them harder to read:
If you look at the scaled down version, you can see parts of the text get cut off and don't look right:
3) Add more contrast to the tabular element documentation.
Sometimes Doxygen will generate docs for elements of a larger type in little tabbed things. This is 100% subjective compared to the above two points, but I wish there was more contrast between the tab's header and body: Old theme (better IMO):
New theme (worse):
