Skip to content

doc: Deprecate doxygen guides and sync changes #21573

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 2 commits into from
Jul 21, 2025
Merged

doc: Deprecate doxygen guides and sync changes #21573

merged 2 commits into from
Jul 21, 2025

Conversation

AnnsAnns
Copy link
Contributor

@AnnsAnns AnnsAnns commented Jul 1, 2025 •
edited
Loading

Contribution description

This syncs any changes that were only added to doxygen and also deprecates all guides that are currently in both starlight and doxygen with one exception, I did not deprecate the structure, while technically in both doxygen and starlight, considering that the structure guide is also a sort-of guide to our API Documentation structure and how to navigate it.

There were 0 changes outside of that, this PR neither adds nor removes any content, it simply redirects/updates the existing guides to be in-sync with each other and deprecate anything that has two sources of truth.

Testing procedure

Build make doc-starlight and make doc

Issues/PRs references

@AnnsAnns AnnsAnns requested review from aabadie and jia200x as code owners July 1, 2025 11:45
@github-actions github-actions bot added the Area: doc Area: Documentation label Jul 1, 2025
@crasbe crasbe added 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 Jul 1, 2025
@riot-ci
Copy link

riot-ci commented Jul 1, 2025 •
edited
Loading

Murdock results

✔️ PASSED

3eda07e doc: move architecture dependencies into starlight guide

Success Failures Total Runtime
1 0 1 02m:05s

Artifacts

@crasbe
Copy link
Contributor

crasbe commented Jul 1, 2025

The change creates a reference error, because the ccache chapter is missing now (from the Doxygen docs):
image

@AnnsAnns
Copy link
Contributor Author

AnnsAnns commented Jul 1, 2025

The change creates a reference error, because the ccache chapter is missing now (from the Doxygen docs): image

Already fixed 😉

mguetschow
mguetschow reviewed Jul 1, 2025
View reviewed changes
doc/doxygen/src/advanced-build-system-tricks.md Outdated
For zsh users a RIOT-aware completion is provided in
`dist/tools/zsh-completion`. Refer to the `README.md` in there for more details
and installation instructions.
@deprecated See [Advanced Build System Tricks](https://guide.riot-os.org/build-system/advanced_build_system_tricks/) on the RIOT Guide Site for the latest information. This page will be removed in a future release.
Copy link
Contributor

Choose a reason for hiding this comment

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

Thanks for doing this!

Suggested change
@deprecated See [Advanced Build System Tricks](https://guide.riot-os.org/build-system/advanced_build_system_tricks/) on the RIOT Guide Site for the latest information. This page will be removed in a future release.
@deprecated See [Advanced Build System Tricks](https://guide.riot-os.org/build-system/advanced_build_system_tricks/) on the RIOT Guide Site for the latest information. This page will be removed after release 2025.11.

and similar on all the other pages

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Ok will do

Copy link
Contributor Author

Choose a reason for hiding this comment

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

done

@AnnsAnns
Copy link
Contributor Author

AnnsAnns commented Jul 1, 2025

I made a few more changes to the getting started and mainpage of doxygen, and I moved the architecture specific dependencies into the guide itself (which is probably something I should have done in the first place)

@AnnsAnns AnnsAnns mentioned this pull request Jul 1, 2025
Open
22 tasks
mguetschow
mguetschow reviewed Jul 1, 2025
View reviewed changes
doc/doxygen/src/mainpage.md Outdated
@@ -48,33 +48,15 @@ RIOT is developed by an open community that anyone is welcome to join:

[mastodon-link]: https://fosstodon.org/@RIOT_OS

The quickest start {#the-quickest-start}
Getting Started {#getting-started}
Copy link
Contributor

Choose a reason for hiding this comment

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

doxygen complains about #getting-started being defined more than once (see above)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Removed the slug

doc/guides/getting-started/installing.mdx
## Architecture Specific Requirements

:::caution[Don't get lost]
Copy link
Contributor

Choose a reason for hiding this comment

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

Would it make sense to move this to a subpage / another guide?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I thought about it but it also feels out of place on its own, in the end this felt like the best location for it.

@AnnsAnns
Copy link
Contributor Author

Did I miss anything in the review that still needs to be done?

@crasbe crasbe requested a review from mguetschow July 10, 2025 09:46
crasbe
crasbe reviewed Jul 10, 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.

I still have to look at the generated documentation.

@crasbe crasbe added the Process: deprecation Integration Process: The PR is deprecating a feature or API label Jul 11, 2025
@crasbe crasbe mentioned this pull request Jul 12, 2025
Merged
crasbe
crasbe approved these changes Jul 15, 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.

Please squash :)

crasbe
crasbe requested changes Jul 15, 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.

Another thing I just noticed: the two images are swapped:
image
Or rather: on a Linux system that is not WSL, you will not see "Installing VS Code Server" output, so that screenshot is a bit redundant IMO.

Not sure if you added that or if it was present before?

@Teufelchen1
Copy link
Contributor

@AnnsAnns I know you are busy with exams, but any chance on getting this in today or tomorrow? Would be nice to have it in the upcoming release.

@AnnsAnns
Copy link
Contributor Author

I will try to get this done tonight no worries

@AnnsAnns AnnsAnns force-pushed the doxygen_deprecation branch from 7f5528c to 3eda07e Compare July 21, 2025 20:20
@AnnsAnns
Copy link
Contributor Author

This should cover everything, if anything else needs to be done let me know and I will try to squash (hehe) it in tomorrow if I have time

@AnnsAnns AnnsAnns mentioned this pull request Jul 21, 2025
Merged
@crasbe crasbe enabled auto-merge July 21, 2025 20:34
@crasbe crasbe added this pull request to the merge queue Jul 21, 2025
@AnnsAnns
Copy link
Contributor Author

Ty 😄

Merged via the queue into RIOT-OS:master with commit 20c7f5d Jul 21, 2025
26 checks passed
@Teufelchen1
Copy link
Contributor

You guys rock!

@mguetschow mguetschow mentioned this pull request Aug 14, 2025
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@maribu maribu maribu left review comments

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

@mguetschow mguetschow Awaiting requested review from mguetschow

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 CI: skip compile test If set, CI server will run only non-compile jobs, but no compile jobs or their dependent jobs Process: deprecation Integration Process: The PR is deprecating a feature or API Type: cleanup The issue proposes a clean-up / The PR cleans-up parts of the codebase / documentation
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
6 participants
@AnnsAnns @riot-ci @crasbe @Teufelchen1 @maribu @mguetschow