Merge pull request #21946 from LasseRosenow/guides-use-file-tree-component

doc: migrate file trees in guides to starlight TreeView component

Author: AnnsAnns

dist/tools/buildsystem_sanity_check/check.sh

@@ -214,6 +214,7 @@ check_cpu_cpu_model_defined_in_makefile_features() {
     patterns+=(-e '^ *\(export\)\? *CPU \??\?=')
     patterns+=(-e '^ *\(export\)\? *CPU_MODEL \??\?=')
     pathspec+=(':!**.md')
+    pathspec+=(':!**.mdx')
     pathspec+=(':!boards/**/Makefile.features')
     pathspec+=(':!cpu/**/Makefile.features')
 

…vanced_tutorials/creating_application.md …anced_tutorials/creating_application.mdxdoc/guides/advanced_tutorials/creating_application.md renamed to doc/guides/advanced_tutorials/creating_application.mdx doc/guides/advanced_tutorials/creating_application.md renamed to doc/guides/advanced_tutorials/creating_application.mdx

@@ -3,6 +3,8 @@ title: Creating an Application
 description: How to create your own application for RIOT
 ---
 
+import FileTree from '@components/FileTree.astro';
+
 To create your own application you need to create a directory containing one or
 multiple C file(s) with your source code and a Makefile. A template Makefile is
 available in the `dist` folder of the
@@ -241,21 +243,23 @@ tree applications, modules and boards are supported.
 For a full application with custom board and modules, the following directory
 tree can be used:
 
-```
-├── apps
-│   └── my_app
-│       └── Makefile
-├── boards
-│   └── my_board
-├── modules
-│   └── my_module
-│       ├── include
-│       │   └── my_module.h
-│       ├── Makefile
-│       ├── Makefile.include
-│       └── my_module.c
-└── RIOT
-```
+<FileTree>
+
+- apps
+    - my_app
+        - Makefile
+- boards
+  - my_board/
+- modules
+    - my_module
+        - include
+            -my_module.h
+        - Makefile
+        - Makefile.include
+        - my_module.c
+- RIOT/
+
+</FileTree>
 
 In this example tree, the `apps` directory contains a collection of applications
 for the project. The modules directory could contain extra modules for the

…s/advanced_tutorials/creating_modules.md …/advanced_tutorials/creating_modules.mdxdoc/guides/advanced_tutorials/creating_modules.md renamed to doc/guides/advanced_tutorials/creating_modules.mdx doc/guides/advanced_tutorials/creating_modules.md renamed to doc/guides/advanced_tutorials/creating_modules.mdx

@@ -3,6 +3,8 @@ title: Creating Modules
 description: Guide on how to create modules in RIOT-OS
 ---
 
+import FileTree from '@components/FileTree.astro';
+
 Modules in RIOT are well-defined units of code that provide a set of features
 to your application. This includes also drivers and to a certain extent ports
 for CPUs and boards (with some exceptions, see the
@@ -47,13 +49,12 @@ in the linker which can be hard to track down.
 
 This problem happened in the past for:
 
- * Packages root directory (libfixmath/u8g2)
- * boards/cpu/periph and their common boards/cpu/periph
+* Packages root directory (libfixmath/u8g2)
+* boards/cpu/periph and their common boards/cpu/periph
 
 Note: even if all boards and cpus implement the `board` and `cpu` modules, only
       one is used in an application so there is no conflict.
 
-
 ## Module Dependencies
 
 Your module may depend on other modules to minimize code duplication. These
@@ -77,6 +78,7 @@ the user needs to add the directory (or directories) containing external modules
 to `EXTERNAL_MODULE_DIRS`.
 
 External modules can optionally define the following files:
+
 * `Makefile.include` file to set global build configuration like `CFLAGS` or add
   API headers include paths to the `USEMODULE_INCLUDES` variable.
 * `Makefile.dep` file to set module dependencies
@@ -114,12 +116,14 @@ These modules appear in RIOT under two forms:
 
 1. Conditionally included source files:
 
-```
-foo
-├── foo_bar.c
-├── foo.c
-└── Makefile
-```
+<FileTree>
+
+- foo
+    - foo_bar.c
+    - foo.c
+    - Makefile
+
+</FileTree>
 
 In `foo/Makefile` you add the source file to the `SRC` variable, conditioned on
 the Pseudomodule inclusion
@@ -134,13 +138,16 @@ See `sys/net/ble/skald` for an example in code.
 
 2. Using the `SUBMODULES` mechanism:
 
-```
-foo
-├── spam.c
-├── ham.c
-├── eggs.c
-└── Makefile
-```
+
+<FileTree>
+
+- foo
+    - spam.c
+    - ham.c
+    - eggs.c
+    - Makefile
+
+</FileTree>
 
 ```makefile
 # make all code end up in "foo_bar.a", this can be any name
@@ -181,16 +188,19 @@ implementation.
 The module source files are created in the `sys` directory.
 
 From the RIOT base directory, run:
+
 ```sh
 make generate-module
 ```
+
 Then answer a few questions about the driver:
-- Module name: enter a name for your module. It will be used as both the name
+
+* Module name: enter a name for your module. It will be used as both the name
   of the module directory under sys, where the source files are created, and
   the build system module (used with `USEMODULE`).
-- Module doxygen name: Enter the name of module, as displayed in the
+* Module doxygen name: Enter the name of module, as displayed in the
   Doxygen documentation.
-- Brief doxygen description: Describe in one line what is this module about.
+* Brief doxygen description: Describe in one line what is this module about.
 
 Other global information (author name, email, organization) should be retrieved
 automatically from your git configuration.

…des/advanced_tutorials/porting_boards.md …es/advanced_tutorials/porting_boards.mdxdoc/guides/advanced_tutorials/porting_boards.md renamed to doc/guides/advanced_tutorials/porting_boards.mdx doc/guides/advanced_tutorials/porting_boards.md renamed to doc/guides/advanced_tutorials/porting_boards.mdx

@@ -3,6 +3,8 @@ title: Porting Boards
 description: Guide on how to port new boards to RIOT-OS
 ---
 
+import FileTree from '@components/FileTree.astro';
+
 At some point you might need to port a new `BOARD` to `RIOT`, either because
 that specific development board is not yet supported or because you have a
 custom `BOARD` for your project.
@@ -31,21 +33,23 @@ Makefiles. Usually a `BOARD` directory has the following structure,
 although not all of the subdirectories or Makefiles have to be present for
 a board implementation to work.
 
-```
-board-foo
-├── dist
-│   └── scripts
-├── board.c
-├── doc.md
-├── include
-│   ├── periph_conf.h
-│   ├── board.h
-│   └── gpio_params.h
-├── Makefile
-├── Makefile.dep
-├── Makefile.features
-└── Makefile.include
-```
+<FileTree>
+
+- board-foo
+    - dist
+        - scripts/
+    - board.c
+    - doc.md
+    - include
+        - periph_conf.h
+        - board.h
+        - gpio_params.h
+    - Makefile
+    - Makefile.dep
+    - Makefile.features
+    - Makefile.include
+
+</FileTree>
 
 ### Source Files
 
@@ -430,22 +434,24 @@ The directory structure of a common folder is very similar to the board
 folder structure and not all files and folders have to be present except for
 the main `Makefile`.
 
-```
-RIOT
-└── boards
-    └── common
-        └── adafruit-nrf52-bootloader
-            ├── board.c
-            ├── doc.md
-            ├── include
-            │   ├── periph_conf.h
-            │   ├── board.h
-            │   └── gpio_params.h
-            ├── Makefile
-            ├── Makefile.dep
-            ├── Makefile.features
-            └── Makefile.include
-```
+<FileTree>
+
+- RIOT
+    - boards
+        - common
+            - adafruit-nrf52-bootloader
+                - board.c
+                - doc.md
+                - include
+                    - periph_conf.h
+                    - board.h
+                    - gpio_params.h
+                - Makefile
+                - Makefile.dep
+                - Makefile.features
+                - Makefile.include
+
+</FileTree>
 
 The main `Makefile` defines the module name for the common board module and
 should follow the general naming scheme of `boards_common_awesome-common-stuff`.
@@ -502,25 +508,26 @@ external boards, e.g.: `EXTERNAL_BOARD_DIRS=/home/external-boards/` (this would
 commonly be done in your application `Makefile` or your environment). You can
 specify multiple directories separated by spaces.
 
-```
-/home
-├── RIOT
-│   └── ...
-└── external-boards
-    └── board-foo
-        ├── dist
-        │   └── scripts
-        ├── board.c
-        ├── doc.md
-        ├── include
-        │   ├── periph_conf.h
-        │   ├── board.h
-        │   └── gpio_params.h
-        ├── Makefile
-        ├── Makefile.dep
-        ├── Makefile.features
-        └── Makefile.include
-```
+<FileTree>
+
+- home
+    - RIOT/
+    - external-boards
+        - board-foo
+            - dist
+                - scripts/
+            - board.c
+            - doc.md
+            - include
+                - periph_conf.h
+                - board.h
+                - gpio_params.h
+            - Makefile
+            - Makefile.dep
+            - Makefile.features
+            - Makefile.include
+
+</FileTree>
 
 If the external `BOARD` is very similar to a `BOARD` already present in
 `RIOTBOARD`, the external `BOARD` (`board-foo`) can inherit from that

doc/guides/c_tutorials/coap.md doc/guides/c_tutorials/coap.mdxdoc/guides/c_tutorials/coap.md renamed to doc/guides/c_tutorials/coap.mdx

@@ -4,6 +4,8 @@ description: Learn how to use CoAP with RIOT
 code_folder: examples/guides/coap
 ---
 
+import FileTree from '@components/FileTree.astro';
+
 CoAP (Constrained Application Protocol) is a protocol to implement REST APIs
 for constrained devices and networks.
 It is designed for IoT applications and is similar to HTTP but much lighter.
@@ -24,11 +26,13 @@ that will feature a more streamlined API and additional functionality.
 
 Create a new directory for your project:
 
-```text
-coap-hello-server
-├── Makefile
-└── main.c
-```
+<FileTree>
+
+- coap-hello-server
+    - Makefile
+    - main.c
+
+</FileTree>
 
 ### Step 2: Create the Makefile
 
@@ -152,11 +156,13 @@ BOARD=arduino-feather-nrf52840-sense make all flash term
 
 Create a new directory for your project:
 
-```text
-coap-hello-client
-├── Makefile
-└── main.c
-```
+<FileTree>
+
+- coap-hello-client
+    - Makefile
+    - main.c
+
+</FileTree>
 
 ### Step 2: Create the Makefile
 

doc/starlight/astro.config.mjs doc/starlight/astro.config.tsdoc/starlight/astro.config.mjs renamed to doc/starlight/astro.config.ts

@@ -1,4 +1,3 @@
-// @ts-check
 import { defineConfig } from "astro/config";
 import starlight from "@astrojs/starlight";
 import rehypeGithubEmoji from "rehype-github-emoji";

doc/starlight/src/components/FileTree.astro

@@ -0,0 +1,7 @@
+---
+import { FileTree as StarlightFileTree } from "@astrojs/starlight/components";
+---
+
+<StarlightFileTree>
+  <slot />
+</StarlightFileTree>

doc/starlight/src/pages/changelog.astro

@@ -1,6 +1,6 @@
 ---
 import StarlightPage from "@astrojs/starlight/components/StarlightPage.astro";
-import { LinkButton, LinkCard } from "@astrojs/starlight/components";
+import { LinkButton, LinkCard, FileTree } from "@astrojs/starlight/components";
 import { getCollection } from "astro:content";
 
 const changelog = await getCollection("changelog");