Skip to content

doc/porting-boards: Change example doc.txt to doc.md#21257

Merged
mguetschow merged 1 commit intoRIOT-OS:masterfrom
crasbe:pr/porting_boards_new
Mar 3, 2025
Merged

doc/porting-boards: Change example doc.txt to doc.md#21257
mguetschow merged 1 commit intoRIOT-OS:masterfrom
crasbe:pr/porting_boards_new

Conversation

@crasbe
Copy link
Copy Markdown
Contributor

@crasbe crasbe commented Feb 28, 2025

Contribution description

As proposed by kfessel in #21220, the best approach to update the doc.txt files with and without broken comment blocks is to convert them to Markdown files to eliminate the code blocks.
This PR updates the documentation in the Porting Boards tutorial and adds a small remark about the change to avoid confusion why existing confusion has a different format.

Also I added the syntax highlighting option, which Doxygen does not seem to render but GitHub does. markdown is not recognized by Doxygen either.

Current State:
Screenshot 2025-02-28 000105

With this PR in Doxygen:
image

With this PR in GitHub:
image

Testing procedure

Generate the documentation and check that everything looks as it should.

Issues/PRs references

This replaces #21252 and depends on #21255.

@github-actions github-actions bot added the Area: doc Area: Documentation label Feb 28, 2025
@crasbe
Copy link
Copy Markdown
Contributor Author

crasbe commented Feb 28, 2025

I wonder if it would make sense to add a remark about riotgen generating doc.txt files or if it would make more sense to just update riotgen?

For example: https://github.com/aabadie/riot-generator/blob/main/riotgen/templates/board/doc.txt.j2

mguetschow
mguetschow approved these changes Feb 28, 2025
View reviewed changes
Copy link
Copy Markdown
Contributor

@mguetschow mguetschow left a comment

Choose a reason for hiding this comment

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

Thanks, looks good!

@mguetschow
Copy link
Copy Markdown
Contributor

mguetschow commented Feb 28, 2025

I wonder if it would make sense to add a remark about riotgen generating doc.txt files or if it would make more sense to just update riotgen?

For example: https://github.com/aabadie/riot-generator/blob/main/riotgen/templates/board/doc.txt.j2

I'd rather have riotgen updated :)

@kfessel
Copy link
Copy Markdown
Contributor

kfessel commented Feb 28, 2025 •
edited
Loading

we need
changes to
doc/doxygen/riot.doxyfile
and
dist/tools/doccheck/check.sh

see #21255.

@crasbe crasbe mentioned this pull request Feb 28, 2025
Merged
@crasbe
Copy link
Copy Markdown
Contributor Author

crasbe commented Feb 28, 2025

I'd rather have riotgen updated :)

I created a PR for this: aabadie/riot-generator#18

@kfessel I know, that's why I added "depends on 21255" in the decription above :)

@crasbe
Copy link
Copy Markdown
Contributor Author

crasbe commented Mar 3, 2025

The changes to riotgen were merged today by aabadie. I added a remark to the documentation that only the latest version (which has yet to be released) will generate doc.md files.

mguetschow
mguetschow approved these changes Mar 3, 2025
View reviewed changes
Copy link
Copy Markdown
Contributor

@mguetschow mguetschow left a comment

Choose a reason for hiding this comment

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

Please squash :)

@mguetschow mguetschow added the CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR label Mar 3, 2025
@crasbe crasbe force-pushed the pr/porting_boards_new branch from b2748b9 to cb0c45b Compare March 3, 2025 12:25
@riot-ci
Copy link
Copy Markdown

riot-ci commented Mar 3, 2025

Murdock results

✔️ PASSED

cb0c45b doc/porting-boards: change example doc.txt to doc.md

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

Artifacts

@mguetschow mguetschow added this pull request to the merge queue Mar 3, 2025
Merged via the queue into RIOT-OS:master with commit e545642 Mar 3, 2025
25 checks passed
@crasbe crasbe deleted the pr/porting_boards_new branch March 3, 2025 13:08
@crasbe
Copy link
Copy Markdown
Contributor Author

crasbe commented Mar 3, 2025

Thanks everyone for working with me to get this done :)

@aabadie
Copy link
Copy Markdown
Contributor

aabadie commented Mar 3, 2025

I'd rather have riotgen updated :)

I created a PR for this: aabadie/riot-generator#18

New riotgen version just published to PyPI: https://pypi.org/project/riotgen/0.11.0/

@crasbe
Copy link
Copy Markdown
Contributor Author

crasbe commented Mar 3, 2025

I'd rather have riotgen updated :)

I created a PR for this: aabadie/riot-generator#18

New riotgen version just published to PyPI: https://pypi.org/project/riotgen/0.11.0/

Thank you for addressing this so quickly :)

@mguetschow mguetschow mentioned this pull request Mar 5, 2025
Merged
@mguetschow mguetschow added this to the Release 2025.04 milestone Apr 8, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@mguetschow mguetschow mguetschow 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: doc Area: Documentation CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR

Projects

None yet

Milestone

Release 2025.04

Development

Successfully merging this pull request may close these issues.

5 participants

@crasbe @mguetschow @kfessel @riot-ci @aabadie