doc/guide: Introduce a Guide Site #21404
Conversation
Woops sorry, did not want to block this draft PR. 😅
|
Progress is now visible at: https://newguides.annsann.eu/ |
|
I recommend to have a look at the Files tab here as well. GitHub is providing some annotations from the CI. |
Will do, ty :) I'm also not too sure how the actual CI build step should look like. Right now its uploading to github pages but as far as I know RIOT doesn't use Github Pages but something else. Another question where I'm still a bit unsure is whether it makes to actually add content already (e.g. currently the build system stuff) or whether that should be moved to a different PR. |
For now let's use pages. For www.riot-os.org, we use a self-deployed Jekyll, that is true. |
I would add that example content already. Otherwise it will be hard to tell if the deployment worked as intended? And it's also important for finding bugs in the rendered output, e.g. what if it only showed correctly in your browser so far? |
|
I guess the file |
|
We should also document how the guide pages itself work. E.g. you get hit by a bus 🚌, how do I, a non-frontend boy, set it up locally for development? Also, how many |
|
Is there a pattern when you use |
mdx will probably be more relevant in the tutorial PR since importing text blocks will be quite useful. Right now using mdx is only a proof of "it works".
In the frontmatter parameters at the top of the file there is a link to the example it compares against, it's
Will do with the build tools and general guides then 👍 Though the general community process/vision stuff requires some special Makefile magic from a quick glance at the doxygen makefile, will have to look into it 😄 |
Thats planned, no better way to showcase the guide site than with a guide ... about the guide site 😛 |
5dee242 to
42256d8
Compare
|
Cool! Squash please! |
doc/guides: How to Doc fix: add starlight to base makefile
Contribution description
(Development Build Screenshot from b8838e1 - Look may have changed over time)
In September of 2024 I started working on improving the beginner experience of RIOT. While working on this with others we quickly realized that several limitations of Doxygen made the UX for beginners a nightmare, even when we had better guides for beginners, given both different target audience and the complicated mess that the auto-generated doxygen output and sidebar is, at which point we decided to look into solutions to improve our current situation. Fast forward nearly 7 months and we reach this PR.
This is an early draft PR to slowly starting discussion about a new site to host guides on. The idea is to create an environment in which we can host both longer in-depth beginner tutorials spanning across multiple different pages and generally useful information that does not directly relate to API Documentation in a far more controlled UX that Doxygen would not be able to allow us, as discussed in the RIOT weekly coordination meeting.
This initial PR is meant to lay down the groundwork/foundation of that site with later PRs then slowly introducing the new tutorials in hopes of keeping them reviewable.
The total milestones for this specific PR are:
The milestones of later PRs would then be: