dist/tools: add static check for missing board doc.md files

[zhqqzn]

Contribution description

This PR adds a static test (.sh script) that checks whether every ported board has a mandatory doc.md file.
The "common" directory is skipped as it's not a standalone ported board.

Testing procedure

./dist/tools/board_doc_check/check.sh
or make static-test

If all boards contain the required doc.md file, the test passes silently. Otherwise, it fails and reports the directories where the required file is missing.

Issues/PRs references

Closes #22224. See also #22221.

Depends on #22221.

Declaration of AI-Tools / LLMs usage:

AI-Tools / LLMs that were used are:

• none

[riot-ci]

Murdock results

✔️ PASSED

76e9269 doc/guides: update porting_boards to require doc.md for new boards

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

Artifacts

• Documentation preview

[crasbe]

Thank you for providing the static test :)

I'm afraid we can't merge it though until #22221 is completed, but perhaps this is a boost in motivation for @AnnsAnns to finish it :)

[zhqqzn]

OK, thanks for the review!

[crasbe]

Perhaps you can use the opportunity to also change the wording in our guides about Porting Boards: https://doc.riot-os.org/advanced_tutorials/porting_boards/#docmd (in doc/guides/advanced_tutorials/porting_boards.mdx)

Something like this:

diff --git a/doc/guides/advanced_tutorials/porting_boards.mdx b/doc/guides/advanced_tutorials/porting_boards.mdx
index 1d0ab59fc4..c4b8f121ec 100644
--- a/doc/guides/advanced_tutorials/porting_boards.mdx
+++ b/doc/guides/advanced_tutorials/porting_boards.mdx
@@ -197,9 +197,12 @@ PROGRAMMER ?= openocd

 ### doc.md

-Although not explicitly needed, if upstreamed and as a general good
-practice, this file holds all `BOARD` documentation. This can include
+This file holds all `BOARD` documentation and is a necessary prerequisite
+for every new board that is ported. This file can (and should) include
 datasheet reference, documentation on how to flash, etc.
+Proper documentation about your board makes it easier for others to use it
+to the full capacity. Remember to also mention any features that are not
+supported yet!

 The documentation must be under the proper doxygen group, you can compile the
 documentation by calling `make doc` and then open the generated html file on

[crasbe]

Looks good. You don't have to necessarily re-request a review, I get e-mail notifications about any changes and any conversation in this PR anyways.

You can squash the three commits regarding the new static test and leave two commits overall: one for the new static test and one for the guides change.

[crasbe]

Thank you for providing the test and congratulations to your first RIOT contribution 🥳

[zhqqzn]

Thank you too (and maribu) for the feedback and suggestions!