dist/tools,doc/doxygen: use `doc-ci` in the doccheck if possible, update to Doxygen 1.15.0 by crasbe · Pull Request #21372 · RIOT-OS/RIOT

crasbe · 2025-04-07T12:24:05Z

Contribution description

Pull Request #21300 introduced Doxygen as a package, which can be used with the make doc-ci command. In order to avoid static test fails, the doccheck script should use doc-ci as well, otherwise errors will be generated in the static tests that would not be an issue in the CI.

I extended the version warning message and gave a hint for the user that make doc-ci can be used to build the Doxygen documentation with the latest Doxygen version:

cbuec@W11nMate:~/RIOTstuff/riot-doxygen/RIOT$ make -C doc/doxygen doxygen-version
make: Entering directory '/home/cbuec/RIOTstuff/riot-doxygen/RIOT/doc/doxygen'
Warning: Doxygen version 1.12.0 is too old. It is recommended to use at least version 1.13.2 to avoid incorrectly formatted output.
You can use 'make doc-ci' to build the documentation with the required Doxygen version, which will be downloaded and (if required) compiled locally.
make: Leaving directory '/home/cbuec/RIOTstuff/riot-doxygen/RIOT/doc/doxygen'

November Update:
Updating Doxygen is a bit of a hen-and-egg problem due to our static-test, therefore I decided to add the Doxygen update to this PR. Every Doxygen update brings a couple more error messages, but tackling them is not the scope of this PR, therefore I extended the exclude patterns.

Testing procedure

Run make static-test and observe that it downloaded Doxygen:

cbuec@W11nMate:~/RIOTstuff/riot-guides/RIOT$ ls -l dist/tools/doxygen/
total 285276
-rw-r--r-- 1 cbuec cbuec      3726 Oct 31 14:38 Makefile
-rwxr-xr-x 1 cbuec cbuec 214331704 Nov 12 23:35 doxygen
drwxr-xr-x 6 cbuec cbuec      4096 Oct 22 09:51 doxygen-1.15.0
-rw-r--r-- 1 cbuec cbuec  77771683 Oct 22 14:05 doxygen-1.15.0.linux.bin.tar.gz

The static test should not fail, also the documentation should still look okay (this I'll have to check myself).

Issues/PRs references

Required for #21292.

Fixes #21106.

riot-ci · 2025-04-07T12:25:43Z

Murdock results

✔️ PASSED

8446315 dist/tools/doxygen: use dlcache for Doxygen download

Success	Failures	Total	Runtime
1	0	1	01m:22s

Artifacts

Documentation preview

crasbe · 2025-04-07T12:29:14Z

Of couse now this is a hen-and-egg problem between #21292 and this 🤣

mguetschow · 2025-04-07T13:19:10Z

In order to avoid static test fails, the doccheck script should use doc-ci as well, otherwise errors will be generated in the static tests that would not be an issue in the CI.

So why not using doc-ci always instead of only when doxygen-version returns non-zero?

crasbe · 2025-04-07T13:22:33Z

In order to avoid static test fails, the doccheck script should use doc-ci as well, otherwise errors will be generated in the static tests that would not be an issue in the CI.

So why not using doc-ci always instead of only when doxygen-version returns non-zero?

When doxygen-version returns no warning, the local Doxygen version is already up to date and there would be no need to download the 78M binary archive from Github.

But I just saw that there should be an else that covers just that 😅

maribu · 2025-04-07T13:26:23Z

When doxygen-version returns no warning, the local Doxygen version is already up to date and there would be no need to download the 78M binary archive from Github.

True, but only for the first run and I believe there would be value in having make static-test match the output of the CI, even at the cost of 78 MiB download on the first run (until wiping the cache or bumping the min release).

crasbe · 2025-04-07T13:33:38Z

Okay, I'm convinced :D

But I would still like to keep the changes to the doc/doxygen/Makefile. Perhaps in a separate commit now?

maribu · 2025-04-07T13:39:55Z

Sounds good. Feel free to squash at will

mguetschow · 2025-04-07T13:51:47Z

But I would still like to keep the changes to the doc/doxygen/Makefile. Perhaps in a separate commit now?

Makes sense to split this out I'd say.

dist/tools/doccheck/check.sh

mguetschow

Thanks a bunch!

crasbe · 2025-04-07T23:38:40Z

Urgh, this seems to need a bit more attention. Apparently Doxygen 1.13.2 has a bug that doesn't parse code blocks correctly:

I'll have to try it with latest, but not tonight.

For example from https://github.com/RIOT-OS/RIOT/blob/master/sys/psa_crypto/doc.md?plain=1:

sys/psa_crypto/doc.md:463: warning: unable to resolve reference to 'porting-software' for \ref command
sys/psa_crypto/doc.md:464: warning: unable to resolve reference to 'porting-hardware' for \ref command
sys/psa_crypto/doc.md:465: warning: unable to resolve reference to 'porting-secure-elements' for \ref command
sys/psa_crypto/doc.md:560: warning: Unsupported xml/html tag <libraryname> found
sys/psa_crypto/doc.md:563: warning: Unsupported xml/html tag <libraryname> found
sys/psa_crypto/doc.md:589: warning: explicit link request to 'if' could not be resolved
sys/psa_crypto/doc.md:590: warning: explicit link request to 'include' could not be resolved
sys/psa_crypto/doc.md:591: warning: explicit link request to 'endif' could not be resolved
sys/psa_crypto/doc.md:597: warning: explicit link request to 'if' could not be resolved
sys/psa_crypto/doc.md:598: warning: explicit link request to 'include' could not be resolved
sys/psa_crypto/doc.md:600: warning: Unsupported xml/html tag <library_context_type_t> found
sys/psa_crypto/doc.md:601: warning: explicit link request to 'endif' could not be resolved
sys/psa_crypto/doc.md:906: warning: explicit link request to 'if' could not be resolved
sys/psa_crypto/doc.md:908: warning: explicit link request to 'endif' could not be resolved
sys/psa_crypto/doc.md:909: warning: explicit link request to 'if' could not be resolved
sys/psa_crypto/doc.md:911: warning: explicit link request to 'endif' could not be resolved
sys/psa_crypto/doc.md:1007: warning: Unsupported xml/html tag <Some> found

As far as I can tell, the code is in valid code blocks and Doxygen 1.9.1 parses it correctly and so does the GitHub markdown preview.

Something seems to make Doxygen unhappy after around line 460-ish.
But that's just one of more examples that have to be fixed before this PR will be freed by the static-test. OR I'd have to extend the exception list.

mguetschow · 2025-04-08T09:40:55Z

As far as I can tell, the code is in valid code blocks

It was not, see #21380

Doxygen 1.9.1 parses it correctly and so does the GitHub markdown preview.

there is indeed a change in how doxygen parses it between 1.9.4 and 1.13.4, but the root cause is indeed the missing end of block.

crasbe · 2025-04-08T10:56:33Z

With #21380, these are the warnings that remain:

cbuec@W11nMate:~/RIOTstuff/riot-psa-crypto-doc/RIOT$ ./dist/tools/doccheck/check.sh
ERROR: Doxygen generates the following warnings:
warning: Tag 'OUTPUT_TEXT_DIRECTION' at line 102 of file '-' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: Tag 'HTML_TIMESTAMP' at line 1366 of file '-' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: Tag 'FORMULA_TRANSPARENT' at line 1671 of file '-' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: Tag 'LATEX_SOURCE_CODE' at line 1984 of file '-' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: Tag 'LATEX_TIMESTAMP' at line 2000 of file '-' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: Tag 'RTF_SOURCE_CODE' at line 2074 of file '-' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: Tag 'DOCBOOK_PROGRAMLISTING' at line 2179 of file '-' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: Tag 'CLASS_DIAGRAMS' at line 2387 of file '-' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: Tag 'DOT_FONTNAME' at line 2429 of file '-' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: Tag 'DOT_FONTSIZE' at line 2436 of file '-' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: Tag 'DOT_TRANSPARENT' at line 2684 of file '-' has become obsolete.
         To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
sys/include/net/gnrc/netif/pktq.h:14: warning: Potential recursion while resolving \ref command!
cpu/rpx0xx/include/periph_cpu.h:234: warning: unable to resolve reference to 'gpio_t' for \ref command
sys/include/net/gnrc/netif/pktq/type.h:13: warning: Potential recursion while resolving \ref command!
boards/common/arduino-mkr/include/periph_conf_common.h:75: warning: Member CLOCK_DIV (macro definition) of file periph_conf_common.h is not documented.
boards/common/native/include/board.h:143: warning: Member SPIFFS_MTD_DEV (macro definition) of file board.h is not documented.
cpu/rpx0xx/include/periph_cpu.h:234: warning: unable to resolve reference to 'gpio_t' for \ref command
cpu/rpx0xx/include/periph_cpu.h:234: warning: unable to resolve reference to 'gpio_t' for \ref command
boards/arduino-nano-33-iot/include/periph_conf.h:69: warning: Member CLOCK_DIV (macro definition) of file periph_conf.h is not documented.
boards/common/arduino-zero/include/periph_conf.h:77: warning: Member CLOCK_DIV (macro definition) of file periph_conf.h is not documented.
boards/feather-m0/include/periph_conf.h:71: warning: Member CLOCK_DIV (macro definition) of file periph_conf.h is not documented.
boards/hamilton/include/periph_conf.h:84: warning: Member CLOCK_DIV (macro definition) of file periph_conf.h is not documented.
boards/samd10-xmini/include/periph_conf.h:88: warning: Member CLOCK_DIV (macro definition) of file periph_conf.h is not documented.
boards/samd20-xpro/include/periph_conf.h:90: warning: Member CLOCK_DIV (macro definition) of file periph_conf.h is not documented.
boards/samd21-xpro/include/periph_conf.h:90: warning: Member CLOCK_DIV (macro definition) of file periph_conf.h is not documented.
boards/samr21-xpro/include/periph_conf.h:90: warning: Member CLOCK_DIV (macro definition) of file periph_conf.h is not documented.
boards/seeeduino_xiao/include/periph_conf.h:73: warning: Member CLOCK_DIV (macro definition) of file periph_conf.h is not documented.
boards/sensebox_samd21/include/periph_conf.h:72: warning: Member CLOCK_DIV (macro definition) of file periph_conf.h is not documented.
boards/serpente/include/periph_conf.h:71: warning: Member CLOCK_DIV (macro definition) of file periph_conf.h is not documented.
cpu/cortexm_common/include/cpu_conf_common.h:96: warning: unable to resolve reference to 'CPU_DEFAULT_IRQ_PRIO' for \ref command
boards/common/sodaq/include/cfg_clock_default.h:72: warning: Member CLOCK_DIV (macro definition) of file cfg_clock_default.h is not documented.
sys/include/ztimer/config.h:182: warning: unable to resolve reference to 'CONFIG_ZTIMER_USEC_ADJUST_SET' for \ref command
sys/include/net/gnrc/netif/pktq.h:14: warning: Potential recursion while resolving \ref command!
sys/include/net/gnrc/netif/pktq.h:14: warning: Potential recursion while resolving \ref command!
sys/include/net/gnrc/netif/pktq/type.h:13: warning: Potential recursion while resolving \ref command!
sys/include/net/gnrc/netif/pktq/type.h:13: warning: Potential recursion while resolving \ref command!
sys/include/string_utils.h:37: warning: Member STRING_UTILS_H (macro definition) of group sys_string_utils is not documented.
doc/doxygen/src/porting-boards.md:53: warning: unable to resolve reference to 'XTIMER_BACKOFF' for \ref command
doc/doxygen/src/porting-boards.md:53: warning: unable to resolve reference to 'XTIMER_BACKOFF' for \ref command
sys/include/net/sock/dodtls.h:136: warning: unable to resolve reference to 'sock_dtls_create()' for \ref command
sys/include/net/sock/dtls.h:34: warning: unable to resolve reference to 'sock_dtls_create()' for \ref command
sys/include/net/sock/dtls.h:44: warning: unable to resolve reference to 'sock_dtls_create()' for \ref command
sys/include/net/sock/dtls.h:263: warning: unable to resolve reference to 'sock_dtls_create()' for \ref command
sys/include/net/sock/dtls.h:429: warning: unable to resolve reference to 'sock_dtls_close()' for \ref command
sys/include/net/sock/dtls.h:1108: warning: unable to resolve reference to 'sock_dtls_create()' for \ref command
sys/include/net/gnrc/pktbuf.h:60: warning: unable to resolve reference to 'CONFIG_GNRC_PKTBUF_SIZE' for \ref command
sys/include/net/gnrc.h:107: warning: unable to resolve reference to 'net_gnrc_netapi::GNRC_NETAPI_MSG_TYPE_RCV' for \ref command
boards/esp32-heltec-lora32-v2/doc.txt:81: warning: unable to resolve reference to 'PWM0_GPIOS' for \ref command
boards/msbiot/doc.txt:71: warning: unable to resolve reference to 'LED0_PIN' for \ref command
boards/msbiot/doc.txt:71: warning: unable to resolve reference to 'LED1_PIN' for \ref command
boards/msbiot/doc.txt:72: warning: unable to resolve reference to 'LED0_ON' for \ref command
boards/msbiot/doc.txt:72: warning: unable to resolve reference to 'LED1_ON' for \ref command
boards/msbiot/doc.txt:75: warning: unable to resolve reference to 'LED0_ON' for \ref command
boards/msbiot/doc.txt:75: warning: unable to resolve reference to 'LED0_OFF' for \ref command
boards/msbiot/doc.txt:75: warning: unable to resolve reference to 'LED0_TOGGLE' for \ref command
boards/msbiot/doc.txt:76: warning: unable to resolve reference to 'LED1_ON' for \ref command
boards/msbiot/doc.txt:76: warning: unable to resolve reference to 'LED1_OFF' for \ref command
boards/msbiot/doc.txt:76: warning: unable to resolve reference to 'LED1_TOGGLE' for \ref command
sys/posix/include/sys/socket.h:464: warning: The following parameter of socket(int domain, int type, int protocol) is not documented:
sys/include/net/gnrc/pktbuf.h:19: warning: unable to resolve reference to 'CONFIG_GNRC_PKTBUF_SIZE' for \ref command
drivers/include/rtt_rtc.h:49: warning: unable to resolve reference to 'RTT_FREQUENCY' for \ref command
drivers/include/rtt_rtc.h:36: warning: unable to resolve reference to 'RTT_FREQUENCY' for \ref command
sys/include/net/gnrc/netif/pktq/type.h:10: warning: Potential recursion while resolving \ref command!
sys/include/net/gnrc/netif/pktq/type.h:10: warning: Potential recursion while resolving \ref command!
boards/esp32-ttgo-t-beam/doc.txt:82: warning: unable to resolve reference to 'PWM0_GPIOS' for \ref command
sys/include/string_utils.h:37: warning: Member STRING_UTILS_H (macro definition) of group sys_string_utils is not documented.
boards/esp32s2-wemos-mini/doc.txt:45: warning: unable to resolve reference to 'esp32s2-wemos-mini_toc' for \ref command
drivers/include/ph_oem.h:179: warning: unable to resolve reference to 'GPIO_IN_PU' for \ref command
drivers/include/ph_oem.h:180: warning: unable to resolve reference to 'GPIO_IN_PD' for \ref command
drivers/include/ph_oem.h:181: warning: unable to resolve reference to 'GPIO_IN_PD' for \ref command
sys/include/net/gnrc/netif.h:216: warning: Potential recursion while resolving \ref command!
sys/include/net/ieee802154_security.h:70: warning: unable to resolve reference to 'ieee802154_sec_context_t::ieee802154_sec_dev_t' for \ref command
sys/include/net/ieee802154_security.h:84: warning: unable to resolve reference to 'ieee802154_sec_context_t::ieee802154_sec_dev_t' for \ref command
sys/include/net/ieee802154_security.h:60: warning: unable to resolve reference to 'ieee802154_sec_context_t::ieee802154_sec_dev_t' for \ref command
<sys/include/net/gnrc/netif/>:1: warning: Potential recursion while resolving \ref command!
<sys/include/net/gnrc/netif/pktq/>:1: warning: Potential recursion while resolving \ref command!
sys/include/net/gnrc/netif/pktq.h:14: warning: Potential recursion while resolving \ref command!
sys/include/net/gnrc/netif/pktq/type.h:13: warning: Potential recursion while resolving \ref command!
sys/include/net/gnrc/netif/pktq/type.h:13: warning: Potential recursion while resolving \ref command!
sys/include/net/gnrc/netif/pktq.h:14: warning: Potential recursion while resolving \ref command!

The first block of warnings would be solved with #21292, the others would require exceptions or have to be fixed...

crasbe · 2025-11-12T22:15:03Z

Phew that was close. I didn't know that Automerge was still enabled from 7 months ago 🤣

crasbe · 2025-11-12T22:58:14Z

Okay, I included the update to Doxygen 1.15.0 in this PR, because otherwise we have a hen-and-egg problem with the static test.

Every Doxygen update brings new warnings, so I had to add some to the exclude_simple file. They really should be fixed, but that is beyond the scope of this PR tbh.

crasbe · 2025-11-13T00:09:33Z

We should probably make use of dlcache for the Doxygen archive, otherweise our CI will download Doxygen for eeeevery build, adding needless traffic and time.

Edit: Done.

AnnsAnns

Output looks good, doccheck works, doxyfile update appears to be correct. Approved 👍

Though, why don't we simply make doc-ci the default for make doc?

crasbe · 2025-11-13T13:01:56Z

Sorry for all the force-pushing, I fixed the tab-space-indentations in two files and disabled the Shellcheck warning for github_annotate.sh.

crasbe · 2025-11-13T13:03:58Z

Though, why don't we simply make doc-ci the default for make doc?

Maybe later, I didn't want to force everyone to download Doxygen if they already have it locally. Also there is a warning if the local Doxygen version is too old that points to doc-ci.

crasbe · 2025-11-13T13:11:54Z

Thank you for the review :)

crasbe requested review from aabadie and jia200x as code owners April 7, 2025 12:24

github-actions bot added Area: doc Area: Documentation Area: tools Area: Supplementary tools labels Apr 7, 2025

crasbe added CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR Area: tools Area: Supplementary tools and removed Area: tools Area: Supplementary tools labels Apr 7, 2025

crasbe requested a review from maribu April 7, 2025 12:26

crasbe force-pushed the pr/doccheck branch from 63544e5 to 0750914 Compare April 7, 2025 14:00

mguetschow reviewed Apr 7, 2025

View reviewed changes

dist/tools/doccheck/check.sh Outdated Show resolved Hide resolved

crasbe force-pushed the pr/doccheck branch from 0750914 to 4d5f8f2 Compare April 7, 2025 14:18

mguetschow approved these changes Apr 7, 2025

View reviewed changes

mguetschow enabled auto-merge April 7, 2025 14:22

crasbe force-pushed the pr/doccheck branch from 4d5f8f2 to 548376e Compare April 7, 2025 22:34

mguetschow mentioned this pull request Apr 8, 2025

sys/psa_crypto/doc: correctly end code block #21380

Merged

crasbe added the Type: enhancement The issue suggests enhanceable parts / The PR enhances parts of the codebase / documentation label Nov 12, 2025

crasbe force-pushed the pr/doccheck branch from 548376e to 21045b9 Compare November 12, 2025 21:46

crasbe requested a review from AnnsAnns as a code owner November 12, 2025 21:46

mguetschow added this pull request to the merge queue Nov 12, 2025

crasbe removed this pull request from the merge queue due to a manual request Nov 12, 2025

crasbe force-pushed the pr/doccheck branch from 85429a7 to 541cd6c Compare November 12, 2025 22:46

crasbe changed the title ~~dist/tools: use doc-ci in the doccheck if possible~~ dist/tools,doc/doxygen: use doc-ci in the doccheck if possible, update to Doxygen 1.15.0 Nov 12, 2025

crasbe requested review from maribu and mguetschow and removed request for maribu November 12, 2025 22:59

This was referenced Nov 12, 2025

drivers/periph/i2c: Replace LaTeX formula with static SVG file in documentation #21876

Merged

doc/doxygen: Change Default to Light Mode #21292

Merged

crasbe force-pushed the pr/doccheck branch from 9a9654d to c8188a0 Compare November 13, 2025 00:44

AnnsAnns approved these changes Nov 13, 2025

View reviewed changes

crasbe force-pushed the pr/doccheck branch 2 times, most recently from 2586533 to c69d6dc Compare November 13, 2025 12:58

crasbe added 5 commits November 13, 2025 14:00

doc: make Doxygen version warning more verbose

fe3b792

dist/tools/doccheck: fix Shellcheck warning

1984468

dist/tools: use doc-ci in the doccheck (if possible)

108856e

doc/doxygen: update to Doxygen 1.15.0

5051b32

dist/tools/doxygen: use dlcache for Doxygen download

8446315

crasbe force-pushed the pr/doccheck branch from c69d6dc to 8446315 Compare November 13, 2025 13:00

AnnsAnns added this pull request to the merge queue Nov 13, 2025

Merged via the queue into RIOT-OS:master with commit 144b149 Nov 13, 2025
25 checks passed

crasbe deleted the pr/doccheck branch November 13, 2025 13:11

leandrolanzieri added this to the Release 2026.01 milestone Jan 13, 2026

Conversation

crasbe commented Apr 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Contribution description

Testing procedure

Issues/PRs references

Uh oh!

riot-ci commented Apr 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Murdock results

Artifacts

Uh oh!

crasbe commented Apr 7, 2025

Uh oh!

mguetschow commented Apr 7, 2025

Uh oh!

crasbe commented Apr 7, 2025

Uh oh!

maribu commented Apr 7, 2025

Uh oh!

crasbe commented Apr 7, 2025

Uh oh!

maribu commented Apr 7, 2025

Uh oh!

mguetschow commented Apr 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

mguetschow left a comment

Choose a reason for hiding this comment

Uh oh!

crasbe commented Apr 7, 2025

Uh oh!

mguetschow commented Apr 8, 2025

Uh oh!

crasbe commented Apr 8, 2025

Uh oh!

Uh oh!

crasbe commented Nov 12, 2025

Uh oh!

crasbe commented Nov 12, 2025

Uh oh!

crasbe commented Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AnnsAnns left a comment

Choose a reason for hiding this comment

Uh oh!

crasbe commented Nov 13, 2025

Uh oh!

crasbe commented Nov 13, 2025

Uh oh!

Uh oh!

crasbe commented Nov 13, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

crasbe commented Apr 7, 2025 •

edited

Loading

riot-ci commented Apr 7, 2025 •

edited

Loading

mguetschow commented Apr 7, 2025 •

edited

Loading

crasbe commented Nov 13, 2025 •

edited

Loading