boards/rpi-pico*: Update and fix documentation and image by crasbe · Pull Request #21218 · RIOT-OS/RIOT

crasbe · 2025-02-15T00:35:22Z

Contribution description

The Raspberry Pi Pico documentation was outdated, OpenOCD supports the RP2040 since version 1.12.0 that was released two years ago.

Furthermore I fixed the Raspberry Pi Pico image and changed the Pico-W image to the one from the documentation with a transparent background.

Doxygen has a ~~bug~~ intended behavior that ***Beware:*** is not rendered as bold-italic but instead it prints Beware:*** in the output. As far as I can tell, this has been present since at least Doxygen 1.8.13 when the documentation was originally added: https://web.archive.org/web/20210921211645/https://doc.riot-os.org/group__boards__rpi__pico.html

~~I filed a bug report with Doxygen about this, but for the time being I replaced it with the HTML tags that work: doxygen/doxygen#11420~~

The screenshot is from 1.13.2 for testing on my machine, but this works for all versions down to 1.8.15 or lower, so it'll work on 1.12.0 from the CI machines as well.

Testing procedure

Create the documentation and see if everything looks good.

crasbe · 2025-02-15T00:59:10Z

Apparently the comment block is used incorrectly, therefore causing the issue with the triple stars.

https://www.doxygen.nl/manual/markdown.html#mddox_emph_spans
https://www.doxygen.nl/manual/markdown.html#mddox_stars

Incorrect:

/**
 * @defgroup ...

Markdown here
*Bold ignored* because Doxygen removes leading stars.

*/

Correct:

/**
 * @defgroup ...
 *
 * Markdown here
 *
 * *Bold not ignored* because Doxygen has a leading star to remove.
 */

Should we change it? There are probably a lot of doc.txt that would(/should?) have to be changed.

A friendly AI crafted this `sed` command for me (after a lot of convincing and some friendly pushing to reconsider the conditions..):

sed -E '/^\/\*\*|^\* |^\*\//!{/^$/!s/^(.*)$/ * \1/}; /^\s*$/s/^.*$/ */' -i doc.txt

It is supposed to ignore lines that start with /**, * and */, however it will add a * to */. I couldn't get ChatGPT to successfully exclude that. But some manual reworking is better than a lot of manual reworking, I guess.

Personally I'm too stupid to successfully craft a RegEx that would work 😅

riot-ci · 2025-02-15T23:37:59Z

Murdock results

✔️ PASSED

4a23ee2 boards/rpi-pico: Add Pico W group to documentation

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

Artifacts

Documentation preview

crasbe · 2025-02-16T02:11:38Z

Should we change it? There are probably a lot of doc.txt that would(/should?) have to be changed.

This assumption was right. I used the following command to find files that have a line that does not start with a slash or a whitespace and the list of potential candidates is 301 entries long. In total, there are 481 doc.txt files in RIOT.
There are some false positives because for example cpu/doc.txt has #ifdefs and therefore some legitimate lines that aren't a comment.

List of potential candidates

RIOT$ find . -name "doc.txt" -exec grep -lE '^[^ /]' {} +
./cpu/msp430/doc.txt
./cpu/stm32/doc.txt
./cpu/esp32/esp-eth/doc.txt
./cpu/esp32/doc.txt
./cpu/cc26xx_cc13xx/doc.txt
./cpu/esp8266/doc.txt
./cpu/qn908x/doc.txt
./cpu/doc.txt
./cpu/rpx0xx/doc.txt
./cpu/kinetis/doc.txt
./cpu/esp_common/esp-wifi/doc.txt
./cpu/esp_common/esp-now/doc.txt
./bootloaders/riotboot_serial/doc.txt
./bootloaders/riotboot_tinyusb_dfu/doc.txt
./bootloaders/riotboot/doc.txt
./bootloaders/riotboot_dfu/doc.txt
./doc.txt
./pkg/uwb-core/doc.txt
./pkg/mynewt-core/doc.txt
./pkg/openwsn/doc.txt
./pkg/lv_drivers/doc.txt
./pkg/lvgl/doc.txt
./pkg/fatfs/doc.txt
./pkg/tinydtls/doc.txt
./boards/remote-reva/doc.txt
./boards/cc1352p-launchpad/doc.txt
./boards/esp32-heltec-lora32-v2/doc.txt
./boards/nucleo-g071rb/doc.txt
./boards/b-u585i-iot02a/doc.txt
./boards/arduino-mkrzero/doc.txt
./boards/feather-m0/doc.txt
./boards/stm32f4discovery/doc.txt
./boards/stm32f3discovery/doc.txt
./boards/seeeduino_arch-pro/doc.txt
./boards/nucleo-f070rb/doc.txt
./boards/spark-core/doc.txt
./boards/atxmega-a1-xplained/doc.txt
./boards/slstk3402a/doc.txt
./boards/gba_cartridge/doc.txt
./boards/avsextrem/doc.txt
./boards/qn9080dk/doc.txt
./boards/nucleo-f303ze/doc.txt
./boards/stm32l0538-disco/doc.txt
./boards/teensy31/doc.txt
./boards/sodaq-autonomo/doc.txt
./boards/iotlab-a8-m3/doc.txt
./boards/nucleo-f767zi/doc.txt
./boards/sipeed-longan-nano/doc.txt
./boards/arduino-zero/doc.txt
./boards/nucleo-l152re/doc.txt
./boards/feather-m0-wifi/doc.txt
./boards/nucleo-f746zg/doc.txt
./boards/arduino-nano-33-ble/doc.txt
./boards/esp32-ethernet-kit-v1_2/doc.txt
./boards/yunjia-nrf51822/doc.txt
./boards/adafruit-pybadge/doc.txt
./boards/stm32mp157c-dk2/doc.txt
./boards/stk3200/doc.txt
./boards/arduino-mkr1000/doc.txt
./boards/nrf51dongle/doc.txt
./boards/nucleo-l053r8/doc.txt
./boards/calliope-mini/doc.txt
./boards/yarm/doc.txt
./boards/microbit/doc.txt
./boards/wemos-zero/doc.txt
./boards/nucleo-l476rg/doc.txt
./boards/same54-xpro/doc.txt
./boards/p-l496g-cell02/doc.txt
./boards/esp8266-sparkfun-thing/doc.txt
./boards/feather-m0-lora/doc.txt
./boards/sodaq-explorer/doc.txt
./boards/atxmega-a3bu-xplained/doc.txt
./boards/arduino-duemilanove/doc.txt
./boards/microduino-corerf/doc.txt
./boards/adafruit-clue/doc.txt
./boards/adafruit-itsybitsy-m4/doc.txt
./boards/nrf52832-mdk/doc.txt
./boards/openmote-b/doc.txt
./boards/xg23-pk6068a/doc.txt
./boards/adafruit-metro-m4-express/doc.txt
./boards/arduino-mkrfox1200/doc.txt
./boards/arduino-nano-33-iot/doc.txt
./boards/nrf52dk/doc.txt
./boards/esp8266-esp-12x/doc.txt
./boards/sodaq-sara-sff/doc.txt
./boards/arduino-leonardo/doc.txt
./boards/nrf5340dk-app/doc.txt
./boards/nucleo-wl55jc/doc.txt
./boards/nucleo-f207zg/doc.txt
./boards/nucleo-l031k6/doc.txt
./boards/weact-f401ce/doc.txt
./boards/p-nucleo-wb55/doc.txt
./boards/nrf52840dk/doc.txt
./boards/native/doc.txt
./boards/esp32s3-wt32-sc01-plus/doc.txt
./boards/adafruit-itsybitsy-nrf52/doc.txt
./boards/bluepill-stm32f103cb/doc.txt
./boards/phynode-kw41z/doc.txt
./boards/microbit-v2/doc.txt
./boards/native64/doc.txt
./boards/omote/doc.txt
./boards/slstk3400a/doc.txt
./boards/ruuvitag/doc.txt
./boards/mcb2388/doc.txt
./boards/derfmega256/doc.txt
./boards/nucleo-f401re/doc.txt
./boards/nrf9160dk/doc.txt
./boards/cc1312-launchpad/doc.txt
./boards/nucleo-f429zi/doc.txt
./boards/acd52832/doc.txt
./boards/esp32s3-usb-otg/doc.txt
./boards/stm32f746g-disco/doc.txt
./boards/samd21-xpro/doc.txt
./boards/nucleo-f446ze/doc.txt
./boards/sltb001a/doc.txt
./boards/alientek-pandora/doc.txt
./boards/frdm-k64f/doc.txt
./boards/arduino-due/doc.txt
./boards/rpi-pico/doc.txt
./boards/rpi-pico-w/doc.txt
./boards/adafruit-grand-central-m4-express/doc.txt
./boards/stk3600/doc.txt
./boards/blackpill-stm32f103c8/doc.txt
./boards/nucleo-g070rb/doc.txt
./boards/e180-zg120b-tb/doc.txt
./boards/stm32l496g-disco/doc.txt
./boards/nucleo-l4r5zi/doc.txt
./boards/esp32s3-devkit/doc.txt
./boards/pba-d-01-kw2x/doc.txt
./boards/remote-pa/doc.txt
./boards/samr21-xpro/doc.txt
./boards/msbiot/doc.txt
./boards/z1/doc.txt
./boards/samr34-xpro/doc.txt
./boards/esp32s3-pros3/doc.txt
./boards/nucleo-f410rb/doc.txt
./boards/slwstk6220a/doc.txt
./boards/nrf52840-mdk-dongle/doc.txt
./boards/bluepill-stm32f030c8/doc.txt
./boards/esp32s2-wemos-mini/doc.txt
./boards/maple-mini/doc.txt
./boards/nucleo-f446re/doc.txt
./boards/feather-nrf52840-sense/doc.txt
./boards/i-nucleo-lrwan1/doc.txt
./boards/nucleo-g474re/doc.txt
./boards/atmega328p-xplained-mini/doc.txt
./boards/pinetime/doc.txt
./boards/weact-f411ce/doc.txt
./boards/stm32f723e-disco/doc.txt
./boards/nucleo-l552ze-q/doc.txt
./boards/lobaro-lorabox/doc.txt
./boards/opencm904/doc.txt
./boards/nucleo-f412zg/doc.txt
./boards/cc1352-launchpad/doc.txt
./boards/stm32f030f4-demo/doc.txt
./boards/nucleo-f042k6/doc.txt
./boards/olimexino-stm32/doc.txt
./boards/nrf52840dongle/doc.txt
./boards/generic-cc2538-cc2592-dk/doc.txt
./boards/samd10-xmini/doc.txt
./boards/nrf52840-mdk/doc.txt
./boards/esp32-wrover-kit/doc.txt
./boards/firefly/doc.txt
./boards/sltb009a/doc.txt
./boards/particle-boron/doc.txt
./boards/msb-430/doc.txt
./boards/nucleo-f103rb/doc.txt
./boards/stm32l476g-disco/doc.txt
./boards/usb-kw41z/doc.txt
./boards/sipeed-longan-nano-tft/doc.txt
./boards/pyboard/doc.txt
./boards/udoo/doc.txt
./boards/nucleo-f072rb/doc.txt
./boards/doc.txt
./boards/esp32c3-devkit/doc.txt
./boards/iotlab-m3/doc.txt
./boards/nucleo-u575zi-q/doc.txt
./boards/esp32-wemos-lolin-d32-pro/doc.txt
./boards/saml21-xpro/doc.txt
./boards/derfmega128/doc.txt
./boards/saml11-xpro/doc.txt
./boards/b-l072z-lrwan1/doc.txt
./boards/atmega1284p/doc.txt
./boards/nucleo-l452re/doc.txt
./boards/slstk3701a/doc.txt
./boards/particle-xenon/doc.txt
./boards/esp8266-olimex-mod/doc.txt
./boards/mbed_lpc1768/doc.txt
./boards/nucleo-g431rb/doc.txt
./boards/openlabs-kw41z-mini/doc.txt
./boards/frdm-k22f/doc.txt
./boards/stm32f769i-disco/doc.txt
./boards/nrf51dk/doc.txt
./boards/esp32-wroom-32/doc.txt
./boards/esp32s2-lilygo-ttgo-t8/doc.txt
./boards/saml10-xpro/doc.txt
./boards/ek-lm4f120xl/doc.txt
./boards/atmega8/doc.txt
./boards/nucleo-f303re/doc.txt
./boards/nucleo-l496zg/doc.txt
./boards/arduino-nano/doc.txt
./boards/remote-revb/doc.txt
./boards/nucleo-l412kb/doc.txt
./boards/blackpill-stm32f103cb/doc.txt
./boards/dwm1001/doc.txt
./boards/nucleo-f091rc/doc.txt
./boards/arduino-mkrwan1300/doc.txt
./boards/serpente/doc.txt
./boards/lsn50/doc.txt
./boards/stm32f429i-disco/doc.txt
./boards/openmote-cc2538/doc.txt
./boards/esp32-ttgo-t-beam/doc.txt
./boards/telosb/doc.txt
./boards/limifrog-v1/doc.txt
./boards/msba2/doc.txt
./boards/zigduino/doc.txt
./boards/esp32-olimex-evb/doc.txt
./boards/same51-curiosity-nano/doc.txt
./boards/stm32f7508-dk/doc.txt
./boards/samd20-xpro/doc.txt
./boards/b-l475e-iot01a/doc.txt
./boards/nucleo-f334r8/doc.txt
./boards/nucleo-f302r8/doc.txt
./boards/esp32-ethernet-kit-v1_0/doc.txt
./boards/atmega256rfr2-xpro/doc.txt
./boards/nucleo-f031k6/doc.txt
./boards/nucleo-f030r8/doc.txt
./boards/nucleo-l432kc/doc.txt
./boards/arduino-uno/doc.txt
./boards/im880b/doc.txt
./boards/cc2650-launchpad/doc.txt
./boards/nucleo-f722ze/doc.txt
./boards/common/slwstk6000b/doc.txt
./boards/common/blxxxpill/doc.txt
./boards/common/atxmega/doc.txt
./boards/common/weact-f4x1cx/doc.txt
./boards/common/doc.txt
./boards/common/nrf52/doc.txt
./boards/common/particle-mesh/doc.txt
./boards/stm32f469i-disco/doc.txt
./boards/mega-xplained/doc.txt
./boards/nucleo-f439zi/doc.txt
./boards/nucleo-l433rc/doc.txt
./boards/gd32vf103c-start/doc.txt
./boards/atxmega-a1u-xpro/doc.txt
./boards/arduino-nano-33-ble-sense/doc.txt
./boards/esp32-ethernet-kit-v1_1/doc.txt
./boards/nucleo-f303k8/doc.txt
./boards/bluepill-stm32f103c8/doc.txt
./boards/esp32-mh-et-live-minikit/doc.txt
./boards/hip-badge/doc.txt
./boards/mulle/doc.txt
./boards/openlabs-kw41z-mini-256kib/doc.txt
./boards/nucleo-l073rz/doc.txt
./boards/f4vi1/doc.txt
./boards/ikea-tradfri/doc.txt
./boards/reel/doc.txt
./boards/msb-430h/doc.txt
./boards/feather-nrf52840/doc.txt
./boards/waveshare-nrf52840-eval-kit/doc.txt
./boards/atmega328p/doc.txt
./boards/cc1350-launchpad/doc.txt
./boards/seeeduino_xiao/doc.txt
./boards/esp32c3-wemos-mini/doc.txt
./boards/airfy-beacon/doc.txt
./boards/cc2538dk/doc.txt
./boards/olimex-msp430-h1611/doc.txt
./boards/hamilton/doc.txt
./boards/particle-argon/doc.txt
./boards/avr-rss2/doc.txt
./boards/nucleo-f411re/doc.txt
./boards/nucleo-f413zh/doc.txt
./boards/slstk3401a/doc.txt
./boards/weact-f401cc/doc.txt
./boards/arduino-mega2560/doc.txt
./boards/stm32f0discovery/doc.txt
./boards/seeedstudio-gd32/doc.txt
./boards/weact-g030f6/doc.txt
./boards/e104-bt5010a-tb/doc.txt
./boards/nz32-sc151/doc.txt
./boards/sensebox_samd21/doc.txt
./boards/cc2650stk/doc.txt
./boards/nucleo-c031c6/doc.txt
./boards/thingy52/doc.txt
./boards/olimex-msp430-h2618/doc.txt
./boards/e104-bt5011a-tb/doc.txt
./boards/stk3700/doc.txt
./boards/nucleo-l011k4/doc.txt
./boards/esp32s3-box/doc.txt
./boards/esp32s2-devkit/doc.txt
./sys/malloc_thread_safe/doc.txt
./sys/net/sock/doc.txt
./sys/net/ble/doc.txt
./sys/net/ble/bluetil/doc.txt
./sys/cxx_ctor_guards/doc.txt
./sys/cpp_new_delete/doc.txt
./sys/shell/doc.txt
./drivers/ccs811/doc.txt
./drivers/sht3x/doc.txt
./drivers/atwinc15x0/doc.txt
./drivers/lsm303agr/doc.txt

I think we should change it for these two files, but I don't really want to change everything else at this point as well 🤣

crasbe · 2025-02-16T02:31:39Z

Okay, so the first fixup commit reverts the HTML tags back to the three stars and the second fixup commit adds the comment stars.
This makes it easy to dismiss them if we don't want to add the comment stars.

The other commit adds the Raspberry Pi Pico W Group to the header files so that they are linked in the documentation as well. The headers are shared between the two boards.

Before:

After:

dylad

Thanks for tackling this !

Should we change it? There are probably a lot of doc.txt that would(/should?) have to be changed.

Now the best thing to do is to open an issue about this so we can have this in mind and slowly fix it.

boards/rpi-pico-w/doc.txt

boards/rpi-pico/doc.txt

mguetschow · 2025-02-17T10:32:36Z

Apparently the comment block is used incorrectly, therefore causing the issue with the triple stars.

Ah, now I finally know what the difference is between these two and why they both exist! +1 for opening a tracking issue and handling separately later. Thanks for digging into it!

crasbe · 2025-02-17T11:18:01Z

Let me know when I should squash this.

I opened an issue #21220 to address the comment block issue.

mguetschow

Looks good then, please squash :)

boards/rpi-pico-w/doc.txt

crasbe · 2025-02-17T13:47:53Z

Thanks everyone for the input on this :)

github-actions bot added Area: doc Area: Documentation Area: boards Area: Board ports labels Feb 15, 2025

crasbe force-pushed the pr/rpico_doc branch from 81e4891 to ab57931 Compare February 15, 2025 01:00

benpicco added CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR CI: skip compile test If set, CI server will run only non-compile jobs, but no compile jobs or their dependent jobs labels Feb 15, 2025

dylad reviewed Feb 17, 2025

View reviewed changes

boards/rpi-pico-w/doc.txt Outdated Show resolved Hide resolved

boards/rpi-pico/doc.txt Outdated Show resolved Hide resolved

crasbe mentioned this pull request Feb 17, 2025

doc: Migrate from doc.txt to doc.md in Markdown Format #21220

Open

mguetschow approved these changes Feb 17, 2025

View reviewed changes

mguetschow reviewed Feb 17, 2025

View reviewed changes

boards/rpi-pico-w/doc.txt Outdated Show resolved Hide resolved

crasbe force-pushed the pr/rpico_doc branch from 3ce5aa8 to 64b18b5 Compare February 17, 2025 12:09

crasbe added 2 commits February 17, 2025 13:22

boards/rpi-pico*: Update and fix documentation and images

1dd5de0

boards/rpi-pico: Add Pico W group to documentation

4a23ee2

crasbe force-pushed the pr/rpico_doc branch from 64b18b5 to 4a23ee2 Compare February 17, 2025 12:23

dylad added this pull request to the merge queue Feb 17, 2025

Merged via the queue into RIOT-OS:master with commit 26e46ae Feb 17, 2025
26 checks passed

crasbe deleted the pr/rpico_doc branch February 17, 2025 13:48

kfessel mentioned this pull request Feb 28, 2025

doc: doc.txt -> doc.md #21255

Merged

mguetschow added this to the Release 2025.04 milestone Apr 8, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

boards/rpi-pico*: Update and fix documentation and image#21218

boards/rpi-pico*: Update and fix documentation and image#21218
dylad merged 2 commits intoRIOT-OS:masterfrom
crasbe:pr/rpico_doc

crasbe commented Feb 15, 2025 •

edited

Loading

Uh oh!

crasbe commented Feb 15, 2025 •

edited

Loading

Uh oh!

riot-ci commented Feb 15, 2025 •

edited

Loading

Uh oh!

crasbe commented Feb 16, 2025

Uh oh!

crasbe commented Feb 16, 2025

Uh oh!

dylad left a comment

Uh oh!

Uh oh!

Uh oh!

mguetschow commented Feb 17, 2025

Uh oh!

crasbe commented Feb 17, 2025

Uh oh!

mguetschow left a comment

Uh oh!

Uh oh!

Uh oh!

crasbe commented Feb 17, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

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

Uh oh!

Contribution description

Testing procedure

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Murdock results

Artifacts

Uh oh!

crasbe commented Feb 16, 2025

Uh oh!

crasbe commented Feb 16, 2025

Uh oh!

dylad left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mguetschow commented Feb 17, 2025

Uh oh!

crasbe commented Feb 17, 2025

Uh oh!

mguetschow left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

crasbe commented Feb 17, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

crasbe commented Feb 15, 2025 •

edited

Loading

crasbe commented Feb 15, 2025 •

edited

Loading

riot-ci commented Feb 15, 2025 •

edited

Loading