Build System: Update Doxygen to >=1.10.0 to fix URLs in Headlines

[crasbe]

Description

While updating the LOSTANDFOUND.md file, I noticed that the headlines are not correctly formatted. After some (a lot) of searching I found out that this is a Doxygen bug ( doxygen/doxygen#10466 ) which has been fixed in version >=1.10.0 ( doxygen/doxygen#10466 (comment) ).

I'm not sure if that was a regression introduced to Doxygen at some point or if it never looked right (which I doubt).
Perhaps something in the RIOT documentation will break when updating Doxygen. For testing, I installed the lastest 1.12.0 and it complained about some configuration options being deprecrated. However my Doxygen knowledge is quite limited, so this might have some side effects or additional effort attached to it.

Current Behavior

This is a screenshot taken from https://doc.riot-os.org/md_LOSTANDFOUND.html

Expected Behaviour

This was rendered on my machine with Doxygen 1.12.0:

[miri64]

I mainly assigned @OlegHahm to figure out, if this somehow conflicts with the cronjob that generates https://doc.riot-os.org/.

[crasbe]

The main headache with this issue is that several Linux distributions don't ship Doxygen 1.10.0 yet. For example, this is the current state for Ubuntu (which I think the CI uses?) https://launchpad.net/ubuntu/+source/doxygen
Therefore it would have to be installed manually, but I don't know much about how the CI works.

The current version of Doxygen is 1.13.2 by the way and the old 1.9.8 is from late 2023 🫠
For some packages the "old is gold" strategy from Debian-based distributions can be quite annoying, but that's beside the point 😅

[OlegHahm]

I just updated the docker container for the build job to the latest Alpine version and doxygen is now at 1.12.0. I also re-delivered the latest webhook that triggers building the documentation. As far as I can tell that seems to have worked.

[crasbe]

It looks fixed indeed. Thank you @OlegHahm :)

[miri64]

I just updated the docker container for the build job to the latest Alpine version and doxygen is now at 1.12.0. I also re-delivered the latest webhook that triggers building the documentation. As far as I can tell that seems to have worked.

Does this also fix the generation by Murdock on PRs?

[OlegHahm]

Not sure I know the entire workflow. There is a webhook called by Github on any push which will trigger to rebuild the documentation. I don't know where (and for what reason) Murdock is involved. Is there some sort of a preview for PRs?

[crasbe]

Worst case we'll have to wait for a day or two and see once the next PR is merged.

[miri64]

Is there some sort of a preview for PRs?

Yes, see e.g. #21154 (comment)

[miri64]

I think this is the dockerfile for the container of the murdock build https://github.com/RIOT-OS/murdock-scripts/blob/master/Dockerfile. With the actual build happening here https://github.com/RIOT-OS/murdock-scripts/blob/master/build.sh#L279-L283. The webhook is only for pushes to master.

[OlegHahm]

The Dockerfile in murdock is based on Ubuntu 22.04 where doxygen is apparently still the 1.9 version. Not sure if updating this dockerfile is easily possible.

[OlegHahm]

But even in newer Ubuntu versions the doxygen package seems to stick to this version.

[miri64]

Maybe we can delegate the Murdock build to your container somehow?

[crasbe]

Another option would be to update doxygen in the bringup of the Docker container. This could be added to the Docker container after the apt-get part:

# Update doxygen manually
RUN wget https://github.com/doxygen/doxygen/releases/download/Release_1_12_0/doxygen-1.12.0.linux.bin.tar.gz \
        -P /tmp && \
        tar -xf /tmp/doxygen-1.12.0.linux.bin.tar.gz -C /tmp && \
        /usr/bin/install -m 755 /tmp/doxygen-1.12.0/bin/doxygen /usr/bin && \
        rm -rf /tmp/doxygen*

IMO it makes sense to have apt-get install doxygen first, which makes sure that all the dependencies are there and then just replace the binary. All the functionality of doxygen is concentrated in that single binary, the helper programs doxyindexer and doxywizard are not used by RIOT as far as I can tell. I created the documentation with only the doxygen binary present in /usr/bin and it worked successfully.

To avoid any potential version collision, it would be possible to add an apt-get remove -y doxygen before the wget:

# Update doxygen manually
RUN apt-get remove -y doxygen && \
        wget https://github.com/doxygen/doxygen/releases/download/Release_1_12_0/doxygen-1.12.0.linux.bin.tar.gz \
        -P /tmp && \
        tar -xf /tmp/doxygen-1.12.0.linux.bin.tar.gz -C /tmp && \
        /usr/bin/install -m 755 /tmp/doxygen-1.12.0/bin/doxygen /usr/bin && \
        rm -rf /tmp/doxygen*

I did not test if the RUN commands work in the container, but the commands themselves work.

[OlegHahm]

On Wed, Jan 22, 2025 at 04:14:35AM -0800, Martine Lenders wrote: Maybe we can delegate the Murdock build to your container somehow?

The question might be: is it important that the docs build on developers' hosts as well.

[crasbe]

On Wed, Jan 22, 2025 at 04:14:35AM -0800, Martine Lenders wrote:
Maybe we can delegate the Murdock build to your container somehow?

The question might be: is it important that the docs build on developers'
hosts as well.

The current state is that you can't predict the doxygen version that developers have. It all depends on their distribution, most likely it'll be Doxygen 1.9.8 for Ubuntu users and maybe a little newer for other distributions.

We could add a remark to https://github.com/RIOT-OS/RIOT/blob/master/CONTRIBUTING.md#writing-documentation that doxygen >= 1.10.0 is highly recommended. Considering the update speed of Ubuntu, that'll be relevant for at least a couple of years.