8000 doc/porting-boards: Change example doc.txt to doc.md by crasbe · Pull Request #21257 · RIOT-OS/RIOT · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 1 commit into from
Mar 3, 2025
Merged

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

merged 1 commit into from
Mar 3, 2025

Conversation

crasbe
Copy link
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
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
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
Contributor

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
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
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
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
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
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
Contributor Author
crasbe commented Mar 3, 2025

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

@aabadie
Copy link
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
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 841B 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
0