Skip to content

boards/nucleo*: Cleanup and Enhance the Documentation#21337

Merged
crasbe merged 3 commits intoRIOT-OS:masterfrom
crasbe:pr/nucleo-doc
Oct 16, 2025
Merged

boards/nucleo*: Cleanup and Enhance the Documentation#21337
crasbe merged 3 commits intoRIOT-OS:masterfrom
crasbe:pr/nucleo-doc

Conversation

@crasbe
Copy link
Copy Markdown
Contributor

@crasbe crasbe commented Mar 29, 2025 •
edited
Loading

Contribution description

Inspired by the work of grouping common code and the new *.doc.md syntax, I started to deduplicate the documentation of the STM32 Nucleo boards.

This PR includes:

Testing procedure

Check that the documentation looks beautiful.

Issues/PRs references

Depends on #21319. Update: now merged.
Depends on #21767. Update: now merged.

Progress for Tracking Issue #21220.

@crasbe crasbe added Area: doc Area: Documentation Type: cleanup The issue proposes a clean-up / The PR cleans-up parts of the codebase / documentation State: waiting for other PR State: The PR requires another PR to be merged first labels Mar 29, 2025
@github-actions github-actions bot added the Area: boards Area: Board ports label Mar 29, 2025
@crasbe crasbe mentioned this pull request Mar 29, 2025
Merged
@crasbe
Copy link
Copy Markdown
Contributor Author

crasbe commented Mar 30, 2025

Some of the Nucleo boards have a remark about the toolchain that is to be used:

RIOT/boards/nucleo-f303k8/doc.txt

Lines 81 to 84 in 48162bd

## Supported Toolchains
For using the ST Nucleo-F303K8 board we strongly recommend the usage of the
[GNU Tools for ARM Embedded Processors](https://launchpad.net/gcc-arm-embedded)
toolchain.

I wonder if that information is still relevant and should be added to the common files or if it's irrelevant and should be removed.

The Launchpad Link is outdated as well: Launchpad is no longer used for the Arm GNU Toolchain releases.

The toolchain is now maintained at Arm: https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain
But most(?) distributions provide an gcc-arm-none-eabi package. Maybe that would be better to mention?

@crasbe crasbe removed the State: waiting for other PR State: The PR requires another PR to be merged first label Apr 1, 2025
@krzysztof-cabaj krzysztof-cabaj mentioned this pull request Aug 1, 2025
Merged
@crasbe crasbe mentioned this pull request Oct 7, 2025
Merged
@crasbe crasbe closed this Oct 8, 2025
@crasbe crasbe reopened this Oct 8, 2025
@crasbe crasbe added State: WIP State: The PR is still work-in-progress and its code is not in its final presentable form yet State: waiting for other PR State: The PR requires another PR to be merged first 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 Oct 8, 2025
@crasbe crasbe marked this pull request as ready for review October 8, 2025 10:58
@crasbe crasbe requested review from aabadie and jia200x as code owners October 8, 2025 10:58
@riot-ci
Copy link
Copy Markdown

riot-ci commented Oct 8, 2025 •
edited
Loading

Murdock results

✔️ PASSED

b6931af boards/nucleo-*: migrate to Flashing Guide, point to common doc

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

Artifacts

@crasbe crasbe added Type: enhancement The issue suggests enhanceable parts / The PR enhances parts of the codebase / documentation and removed State: waiting for other PR State: The PR requires another PR to be merged first labels Oct 8, 2025
This was referenced Oct 9, 2025
Merged
Merged
Merged
@krzysztof-cabaj krzysztof-cabaj mentioned this pull request Oct 13, 2025
Merged
@crasbe
Copy link
Copy Markdown
Contributor Author

crasbe commented Oct 15, 2025 •
edited
Loading

In #21794 (comment) I wrote that an OpenOCD update guide doesn't really belong in the guide...
Well:

RIOT/boards/nucleo-l552ze-q/doc.md

Lines 42 to 55 in 744d3c0

@note The upstream version of OpenOCD doesn't contain yet support for this board,
so the source code version from http://openocd.zylin.com/#/c/5510
must be built to be able to flash this board (adapt the configure command with
your preferred installation directory):
```
$ git clone https://git.code.sf.net/p/openocd/code openocd
$ cd openocd
$ git fetch http://openocd.zylin.com/openocd refs/changes/10/5510/5 && git checkout FETCH_HEAD
$ ./bootstrap
$ ./configure --prefix=<installation directory>
$ make -j
$ sudo make install
```

Perhaps I should copy that and add it to the guide nevertheless 🤷‍♂️

Although this case underlines the reason for doing this change: That remark was added in 2020 and OpenOCD 0.11.0 from 2021 already supports that board. Hints like that tend to become quietly outdated unfortunately.

@crasbe crasbe removed the State: WIP State: The PR is still work-in-progress and its code is not in its final presentable form yet label Oct 15, 2025
@crasbe crasbe requested a review from AnnsAnns October 15, 2025 14:03
@crasbe
Copy link
Copy Markdown
Contributor Author

crasbe commented Oct 15, 2025

Perhaps I should copy that and add it to the guide nevertheless 🤷‍♂️

I think this is the wrong spot. We should rather have a combined OpenOCD guide, but this is beyond the scope of this PR.

@AnnsAnns
Copy link
Copy Markdown
Member

AnnsAnns commented Oct 15, 2025

Oh heck, that's one gigantic PR

crasbe
crasbe commented Oct 15, 2025
View reviewed changes
Copy link
Copy Markdown
Contributor Author

@crasbe crasbe left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some typos.

@AnnsAnns
Copy link
Copy Markdown
Member

AnnsAnns commented Oct 15, 2025

Crasbe fixing the issues from Crasbes review of Crasbes PR 😛

image

AnnsAnns
AnnsAnns reviewed Oct 15, 2025
View reviewed changes
Copy link
Copy Markdown
Member

@AnnsAnns AnnsAnns left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

😵‍💫 Given the repetitions I'm not completely surprised if I missed something but for the most part this looks good

@crasbe crasbe mentioned this pull request Oct 15, 2025
Closed
AnnsAnns
AnnsAnns approved these changes Oct 16, 2025
View reviewed changes
Copy link
Copy Markdown
Member

@AnnsAnns AnnsAnns left a comment •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Keeping in mind that the motor stuff appears to be handled in another PR, I'd still really like somebody else to also take a look at this before this gets merged, mostly because it feels like my brain goes into trance after the fifth board description and I don't feel confident enough to say that my review is enough.

I can say that it builds everything & looks alright in doxygen. Thank you for this PR :)

@Teufelchen1
Copy link
Copy Markdown
Contributor

Teufelchen1 commented Oct 16, 2025

Scrolled through it in the aforementioned trance mode and found nothing to complain about. lgtm

@AnnsAnns
Copy link
Copy Markdown
Member

AnnsAnns commented Oct 16, 2025

Will this now have to wait for #20429? I don't think this can even be merged right now, due to the failing CI test for code that you didn't really touch.

@crasbe crasbe force-pushed the pr/nucleo-doc branch 3 times, most recently from 0a583b5 to a626a3c Compare October 16, 2025 12:05
@github-actions github-actions bot added the Area: tools Area: Supplementary tools label Oct 16, 2025
@crasbe
Copy link
Copy Markdown
Contributor Author

crasbe commented Oct 16, 2025

Will this now have to wait for #20429? I don't think this can even be merged right now, due to the failing CI test for code that you didn't really touch.

I updated the exclude pattern file that previously already included the warnings. The reason this popped up is that the warnings are now not in a group but in a file.

@crasbe crasbe added this pull request to the merge queue Oct 16, 2025
Merged via the queue into RIOT-OS:master with commit ce69265 Oct 16, 2025
25 checks passed
@crasbe crasbe deleted the pr/nucleo-doc branch October 16, 2025 12:26
@crasbe crasbe mentioned this pull request Oct 17, 2025
Merged
@benpicco benpicco added this to the Release 2025.10 milestone Dec 3, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@AnnsAnns AnnsAnns AnnsAnns approved these changes

@aabadie aabadie Awaiting requested review from aabadie aabadie is a code owner

@jia200x jia200x Awaiting requested review from jia200x jia200x is a code owner

Assignees

No one assigned

Labels

Area: boards Area: Board ports Area: doc Area: Documentation Area: tools Area: Supplementary tools 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 Type: cleanup The issue proposes a clean-up / The PR cleans-up parts of the codebase / documentation Type: enhancement The issue suggests enhanceable parts / The PR enhances parts of the codebase / documentation

Projects

None yet

Milestone

Release 2025.10

Development

Successfully merging this pull request may close these issues.

5 participants

@crasbe @riot-ci @AnnsAnns @Teufelchen1 @benpicco