Improve Doxygen CSS

[wxtrac]

Issue migrated from trac ticket # 18849

component: documentation | priority: normal

2020-07-23 16:36:11: @vadz created the issue

---

I have to agree that people complaining about rather average look of our docs have a point. It seems like it should be possible to spruce them up a little (and maybe also make them more readable by not spreading the 1-2 line descriptions over the whole page width) by just customizing CSS but I'm not at all the best placed person to do it.

I wonder if anybody less design-challenged than me could consider trying to improve this before 3.2? TIA for any help!

[wxtrac]

2020-07-29 20:42:32: @tierra commented

---

It's worth pointing out that newer versions of Doxygen have gone through a significant facelift. So, before wasting any time tweaking styles, it'd be best to perform an upgrade to the latest version first.

Of course, that's something that will likely take a significant effort itself.

[wxtrac]

2020-07-29 20:45:44: @tierra commented

---

Well, maybe it's not that significant of changes to styles, looking at newer examples now, but regardless, styles have been tweaked a bit in newer versions.

[wxtrac]

2020-08-05 23:26:26: @vadz commented

---

There is this theme, which looks nice, but it doesn't support inheritance graphs which is something we do want to have, I think.

[vadz]

Here is another candidate.

[vadz]

Replacing our CSS should also fix #19276.

[vadz]

After testing the doxygen-awesome theme, there are a few problems that would need to be fixed before we can use it:

• The screenshots page layout is broken with it because the rows containing screenshots don't expand to the entire width of the page any more.
• With 1.8.17 currently used we need some extra hacks to fix "Search" appearance, see Buggy Search Bar when SERVER_BASED_SEARCH=YES jothepro/doxygen-awesome-css#68
• It would be nice to use the dark mode switch in this theme, but this has its own problems:
• The button is not positioned correctly with 1.8.17 (but is fine with 1.9.3).
• Our extra_stylesheet.css hardcodes a few colours that become invisible in dark mode. It should probably be possible to define different colours for the light and dark modes in CSS, but I don't know how to do it.

I could set things up in the GitHub workflow to use doxygen 1.9.3 if necessary, but I'd really appreciate if someone could deal with the CSS fixes that we're going to need.

[vadz]

See https://github.com/mattnotmitt/doxygen-action for an action that could be used to run newer Doxygen in our workflow.

[vadz]

If we switch to 1.9.3, we need to check that the XRC format and RE syntax overviews appearances, as they were reported as being broken with it in this post. And 1.9.4 seems to break CHM, so we probably shouldn't update to it before 3.3 branch start when I'll be very tempted to just drop CHM generation entirely.

[Randalphwa]

This was fixed in #22461 and I've been building CHM files using 1.9.3 ever since, and have yet to see any new problems (there are some really annoying things about the keyword index in the CHM file, but that's been that way for a long time).

1.9.4 changes the way the menu at the top of HTML pages looks, taking up more screen real estate -- but that might not be the case if you switch to the above-mentioned theme.