Doxygen 1.9.7 breaks cool URIs

[wismill]

Doxygen 1.9.7 breaks our cool URIs (see “Cool URIs don’t change”) system, i.e. our system to maintain stable documentation pages via redirection.

See #346 (comment).

I pinned Doxygen version for macOS in #346, but the issue will raise someday for Linux too. Indeed, their current master introduce even more changes. It is not clear how to handle these unforeseen changes. See: doxygen/doxygen/issues/10146.

(EDIT: more context)

[whot]

heh, I wasted quite a lot of time here trying to figure out what exactly about our URLs was cool... turns out it's just the nomenclature from this article and just means "URLs must not change", otherwise everyone is unhappy.

[wismill]

@whot Sorry, I did not know it before Ran presented it to me. I adopted it (what a name), but I agree it is not self-explanatory. I edited the description of this issue.

It does not look Doxygen has a clear roadmap about this, because there are new differences between 1.9.7 and their master branch. They do intend to avoid these changes, but I doubt they have regression tests for that.

I could update our script to handle various Doxygen version, but the approach is still hacky.

I did try using other documentation generator. It seems Doxygen is best in class for code analysis. There are tools like Breathe that try to reuse Doxygen XML output, but then this is yet another tool to maintain in the pipeline.

Do you know/want another documentation generator, or should we fix our cool URIs script?

[whot]

I agree it is not self-explanatory.

tbf, maybe the rest of the world may know it as "cool URLs" and I'm just not cool enough :)

I could update our script to handle various Doxygen version, but the approach is still hacky.

The only purpose for the documentation is to eventually show up on https://xkbcommon.org/ - I doubt there's a lot of use-cases that require it to be run and distributed locally (and do the URLS even matter then? probably not)

Which means that we could have a single CI job with a pinned version of doxygen that produces a tarball that @bluetech can upload on releases. At least until #326 becomes a thing :)

That pinned version could either be a manually built doxygen version or just use something that changes really slowly (i.e. Debian) so we only have to do these checks once every few years. AFAIK we don't really use any doxygen fanciness that requires keeping up-to-date with the latest version.

TLDR: using a stable debian with a (working) doxygen version to produce the docs is the least effort for years to come.

Thoughts?

[wismill]

I made the cool URIs optional in #351. The flag that activates them is intended to be set for the CI that will generate the doc with a pinned version of Doxygen.

[bluetech]

While I approved #351, I'd say that my initial comment was about (trying to) avoid gratuitous URL changes on our side, because broken links are annoying. But if doxygen itself is being uncool, I think the battle is lost, not much to do except ask them to be cooler 😎. In some respects it might be better to just do the breakage as soon as possible, then it will be stable for longer in the future :)

[bluetech]

OFF TOPIC

BTW, I just built with the new doxygen (updated by my package manager), and I get some warnings

warning: Tag 'HTML_TIMESTAMP' at line 43 of file '/home/ran/src/libxkbcommon/build/Doxyfile' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
/home/ran/src/libxkbcommon/doc/introduction-to-xkb.md:67: warning: unable to resolve reference to 'rule-file-format' for \ref command
/home/ran/src/libxkbcommon/doc/introduction-to-xkb.md:181: warning: unable to resolve reference to 'keymap-text-format-v1' for \ref command
/home/ran/src/libxkbcommon/doc/rules-format.md:10: warning: unable to resolve reference to 'xkb-intro' for \ref command

I'll take a look at them probably tomorrow (unless you beat me to it).

[wismill]

@bluetech Doxygen breaks regularly. Last time I check there was no real regression suite, so it’s not surprising. But are there an alternatives? Last time I check the main alternatives were built on top of Doxygen, making the setup even more difficult to maintain and easy to break.