Skip to content

doc/guides: improve guides and many small fixes #21730

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 4 commits into from
Sep 23, 2025
Merged

doc/guides: improve guides and many small fixes #21730

merged 4 commits into from
Sep 23, 2025

Conversation

@LasseRosenow
Copy link
Member

@LasseRosenow LasseRosenow commented Sep 19, 2025 •
edited
Loading

Contribution description

  • Removed code screenshots that are redundant and have replaced others with proper code blocks
  • Fixed deprecated links in some files
  • Deprecated some doxygen pages
  • Addes some more pages to the guides
  • Fixed heading levels => only one h1 per md file

@github-actions github-actions bot added the Area: doc Area: Documentation label Sep 19, 2025
AnnsAnns
AnnsAnns reviewed Sep 19, 2025
View reviewed changes
Copy link
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.

Lasse asked me to give my opinions here so I might as well 😉 Everything builds fine and this is definitely a good change, the previous iteration over relied on screenshots, partly because it was written while working on argon and we didnt have syntax highlighting yet. That would have also made the guides really annoying to update I mean, there were already like 3 different vscode themes in the screenshots by now

@crasbe crasbe added Type: enhancement The issue suggests enhanceable parts / The PR enhances parts of the codebase / documentation Impact: minor The PR is small in size and might only require a quick look of a knowledgeable reviewer Type: cleanup The issue proposes a clean-up / The PR cleans-up parts of the codebase / documentation 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 Sep 19, 2025
@riot-ci
Copy link

riot-ci commented Sep 19, 2025 •
edited
Loading

Murdock results

✔️ PASSED

f5b8144 doc: standardize capitalizations and fix urls

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

Artifacts

@LasseRosenow
Copy link
Member Author

LasseRosenow commented Sep 19, 2025

I addressed your feedback :) Thank you @AnnsAnns!

@AnnsAnns
Copy link
Member

AnnsAnns commented Sep 19, 2025

Very epic ty, now its time for the real reviewers to find 500 whitespaces 😛

@LasseRosenow
Copy link
Member Author

LasseRosenow commented Sep 19, 2025

Very epic ty, now its time for the real reviewers to find 500 whitespaces 😛

I was very cautious not to accidentally reformat :D But we maybe should format those files eventually, my linter paints everything in orange haha

@crasbe
Copy link
Contributor

crasbe commented Sep 19, 2025

Very epic ty, now its time for the real reviewers to find 500 whitespaces 😛

Not 500, but more than 100: The indentation of the C-Code is incorrect. RIOT uses four spaces instead of two per indentation level.

@LasseRosenow
Copy link
Member Author

LasseRosenow commented Sep 19, 2025

but more than 100

😱😱😱😱😱

@github-actions github-actions bot added the Area: examples Area: Example Applications label Sep 19, 2025
@LasseRosenow
Copy link
Member Author

LasseRosenow commented Sep 19, 2025

Okay I have now reformatted the examples and also fixed the formatting in the code blocks in these guides.
I hope I didn't miss something

@LasseRosenow LasseRosenow changed the title doc/guides: replace code screenshots with code blocks and reformat a little bit doc/guides: replace code screenshots with code blocks and fix heading levels in many guide pages Sep 19, 2025
@LasseRosenow
Copy link
Member Author

LasseRosenow commented Sep 19, 2025 •
edited
Loading

Okay while fixing some things I noticed that also heading levels were broken in many files.

So in starlight you already have a level one heading from the frontmatter.
So all headings after that must at least be level 2.

So # Heading is illegal.
Only write ## Heading and more.

Having multiple level one headings also has negative side effects. Because for the outline on the right side of the page level one headings are ignored, which made the outline extremely confusing in many pages.

I fixed it everywhere under /doc/guides.

@LasseRosenow
Copy link
Member Author

LasseRosenow commented Sep 19, 2025

I am now done doing more changes and ready for another review :)

crasbe
crasbe reviewed Sep 22, 2025
View reviewed changes
@crasbe crasbe removed the Impact: minor The PR is small in size and might only require a quick look of a knowledgeable reviewer label Sep 22, 2025
@LasseRosenow LasseRosenow changed the title doc/guides: replace code screenshots with code blocks and fix heading levels in many guide pages doc/guides: improve guides and many small fixes Sep 22, 2025
@LasseRosenow LasseRosenow force-pushed the guides-replace-screenshots-with-code branch 5 times, most recently from 57e1cee to b7a84b2 Compare September 22, 2025 17:54
@LasseRosenow
Copy link
Member Author

LasseRosenow commented Sep 22, 2025

Okay I merged my other newer PRs into this one and rebased everything. This is now again ready for review :)

@github-actions github-actions bot added Area: tests Area: tests and testing framework Area: build system Area: Build system Area: tools Area: Supplementary tools Platform: ESP Platform: This PR/issue effects ESP-based platforms Area: cpu Area: CPU/MCU ports labels Sep 23, 2025
crasbe
crasbe approved these changes Sep 23, 2025
View reviewed changes
Copy link
Contributor

@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.

LGTM, please squash :)

@crasbe crasbe requested a review from AnnsAnns September 23, 2025 15:44
@LasseRosenow LasseRosenow force-pushed the guides-replace-screenshots-with-code branch 2 times, most recently from 0277ea6 to 77af9f6 Compare September 23, 2025 16:11
@LasseRosenow LasseRosenow force-pushed the guides-replace-screenshots-with-code branch from 77af9f6 to f5b8144 Compare September 23, 2025 16:20
@LasseRosenow
Copy link
Member Author

LasseRosenow commented Sep 23, 2025 •
edited
Loading

Squashed :)

AnnsAnns
AnnsAnns requested changes Sep 23, 2025
View reviewed changes
Copy link
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.

Thank you for the (honestly far more than I expected) improvements to everything guide related. This PR is seriously cool 🐸 🎉

doc/doxygen/riot.doxyfile
src/io-mapping-and-shields.md \
src/changelog.md \
../../LOSTANDFOUND.md \
src/LOSTANDFOUND.md \
Copy link
Member

@AnnsAnns AnnsAnns Sep 23, 2025

Choose a reason for hiding this comment

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

Suggested change
src/LOSTANDFOUND.md \
src/LOSTANDFOUND-deprecated.md \

This feels like nitpicking but why are the other ones called "title"-deprecated and this one is just "title"
(ofc requires the file to be renamed too)

Copy link
Member Author

@LasseRosenow LasseRosenow Sep 23, 2025

Choose a reason for hiding this comment

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

I called some files -deprecated because the old file still also exists. Usually we don't call them deprecated.

I just in this case needed to have some suffix, because we still copy the files from other places over to generate the man page and latex target.

I still have no idea if anyone needs this and I am happy to totally remove those files from there also, but for now I just decided not to touch it.

Copy link
Member

@AnnsAnns AnnsAnns Sep 23, 2025

Choose a reason for hiding this comment

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

Good enough for me 👍

AnnsAnns
AnnsAnns approved these changes Sep 23, 2025
View reviewed changes
Copy link
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.

You have my approval boss man 🫡

@crasbe crasbe added this pull request to the merge queue Sep 23, 2025
Merged via the queue into RIOT-OS:master with commit 3d8a5bd Sep 23, 2025
29 checks passed
@LasseRosenow LasseRosenow deleted the guides-replace-screenshots-with-code branch September 24, 2025 06:14
@AnnsAnns AnnsAnns mentioned this pull request Sep 24, 2025
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@crasbe crasbe crasbe approved these changes

@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

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

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

Assignees

No one assigned

Labels

Area: build system Area: Build system Area: cpu Area: CPU/MCU ports Area: doc Area: Documentation Area: examples Area: Example Applications Area: tests Area: tests and testing framework 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 Platform: ESP Platform: This PR/issue effects ESP-based platforms 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

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@LasseRosenow @riot-ci @AnnsAnns @crasbe