kaspar/RIOT
1
0
Fork 0
mirror of https://github.com/RIOT-OS/RIOT.git synced 2025-12-16 10:03:50 +01:00
Code Releases Activity

doc: migrate file trees in guides to starlight TreeView component

Browse Source
This commit is contained in:
Lasse Rosenow 2025-12-09 16:50:19 +01:00
parent 526ac4c69e
commit 670a36bbe6
No known key found for this signature in database
6 changed files with 129 additions and 95 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
doc/guides/advanced_tutorials/creating_application.md → doc/guides/advanced_tutorials/creating_application.mdx
View File

@ -3,6 +3,8 @@ title: Creating an Application
description: How to create your own application for RIOT 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 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 multiple C file(s) with your source code and a Makefile. A template Makefile is
available in the `dist` folder of the 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 For a full application with custom board and modules, the following directory
tree can be used: tree can be used:
``` <FileTree>
├── apps
│ └── my_app - apps
│ └── Makefile - my_app
├── boards - Makefile
│ └── my_board - boards
├── modules - my_board/
│ └── my_module - modules
│ ├── include - my_module
│ │ └── my_module.h - include
│ ├── Makefile -my_module.h
│ ├── Makefile.include - Makefile
│ └── my_module.c - Makefile.include
└── RIOT - my_module.c
``` - RIOT/
</FileTree>
In this example tree, the `apps` directory contains a collection of applications In this example tree, the `apps` directory contains a collection of applications
for the project. The modules directory could contain extra modules for the for the project. The modules directory could contain extra modules for the

44
doc/guides/advanced_tutorials/creating_modules.md → doc/guides/advanced_tutorials/creating_modules.mdx
View File

@ -3,6 +3,8 @@ title: Creating Modules
description: Guide on how to create modules in RIOT-OS 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 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 to your application. This includes also drivers and to a certain extent ports
for CPUs and boards (with some exceptions, see the for CPUs and boards (with some exceptions, see the
@ -53,7 +55,6 @@ This problem happened in the past for:
Note: even if all boards and cpus implement the `board` and `cpu` modules, only 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. one is used in an application so there is no conflict.
## Module Dependencies ## Module Dependencies
Your module may depend on other modules to minimize code duplication. These 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`. to `EXTERNAL_MODULE_DIRS`.
External modules can optionally define the following files: External modules can optionally define the following files:
* `Makefile.include` file to set global build configuration like `CFLAGS` or add * `Makefile.include` file to set global build configuration like `CFLAGS` or add
API headers include paths to the `USEMODULE_INCLUDES` variable. API headers include paths to the `USEMODULE_INCLUDES` variable.
* `Makefile.dep` file to set module dependencies * `Makefile.dep` file to set module dependencies
@ -114,12 +116,14 @@ These modules appear in RIOT under two forms:
1. Conditionally included source files: 1. Conditionally included source files:
``` <FileTree>
foo
├── foo_bar.c - foo
├── foo.c - foo_bar.c
└── Makefile - foo.c
``` - Makefile
</FileTree>
In `foo/Makefile` you add the source file to the `SRC` variable, conditioned on In `foo/Makefile` you add the source file to the `SRC` variable, conditioned on
the Pseudomodule inclusion the Pseudomodule inclusion
@ -134,13 +138,16 @@ See `sys/net/ble/skald` for an example in code.
2. Using the `SUBMODULES` mechanism: 2. Using the `SUBMODULES` mechanism:
```
foo <FileTree>
├── spam.c
├── ham.c - foo
├── eggs.c - spam.c
└── Makefile - ham.c
``` - eggs.c
- Makefile
</FileTree>
```makefile ```makefile
# make all code end up in "foo_bar.a", this can be any name # 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. The module source files are created in the `sys` directory.
From the RIOT base directory, run: From the RIOT base directory, run:
```sh ```sh
make generate-module make generate-module
``` ```
Then answer a few questions about the driver: 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 of the module directory under sys, where the source files are created, and
the build system module (used with `USEMODULE`). 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. 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 Other global information (author name, email, organization) should be retrieved
automatically from your git configuration. automatically from your git configuration.

107
doc/guides/advanced_tutorials/porting_boards.md → doc/guides/advanced_tutorials/porting_boards.mdx
View File

@ -3,6 +3,8 @@ title: Porting Boards
description: Guide on how to port new boards to RIOT-OS 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 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 that specific development board is not yet supported or because you have a
custom `BOARD` for your project. 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 although not all of the subdirectories or Makefiles have to be present for
a board implementation to work. a board implementation to work.
``` <FileTree>
board-foo
├── dist - board-foo
│ └── scripts - dist
├── board.c - scripts/
├── doc.md - board.c
├── include - doc.md
│ ├── periph_conf.h - include
│ ├── board.h - periph_conf.h
│ └── gpio_params.h - board.h
├── Makefile - gpio_params.h
├── Makefile.dep - Makefile
├── Makefile.features - Makefile.dep
└── Makefile.include - Makefile.features
``` - Makefile.include
</FileTree>
### Source Files ### 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 folder structure and not all files and folders have to be present except for
the main `Makefile`. the main `Makefile`.
``` <FileTree>
RIOT
└── boards - RIOT
└── common - boards
└── adafruit-nrf52-bootloader - common
├── board.c - adafruit-nrf52-bootloader
├── doc.md - board.c
├── include - doc.md
│ ├── periph_conf.h - include
│ ├── board.h - periph_conf.h
│ └── gpio_params.h - board.h
├── Makefile - gpio_params.h
├── Makefile.dep - Makefile
├── Makefile.features - Makefile.dep
└── Makefile.include - Makefile.features
``` - Makefile.include
</FileTree>
The main `Makefile` defines the module name for the common board module and 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`. 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 commonly be done in your application `Makefile` or your environment). You can
specify multiple directories separated by spaces. specify multiple directories separated by spaces.
``` <FileTree>
/home
├── RIOT - home
│ └── ... - RIOT/
└── external-boards - external-boards
└── board-foo - board-foo
├── dist - dist
│ └── scripts - scripts/
├── board.c - board.c
├── doc.md - doc.md
├── include - include
│ ├── periph_conf.h - periph_conf.h
│ ├── board.h - board.h
│ └── gpio_params.h - gpio_params.h
├── Makefile - Makefile
├── Makefile.dep - Makefile.dep
├── Makefile.features - Makefile.features
└── Makefile.include - Makefile.include
```
</FileTree>
If the external `BOARD` is very similar to a `BOARD` already present in If the external `BOARD` is very similar to a `BOARD` already present in
`RIOTBOARD`, the external `BOARD` (`board-foo`) can inherit from that `RIOTBOARD`, the external `BOARD` (`board-foo`) can inherit from that

26
doc/guides/c_tutorials/coap.md → doc/guides/c_tutorials/coap.mdx
View File

@ -4,6 +4,8 @@ description: Learn how to use CoAP with RIOT
code_folder: examples/guides/coap code_folder: examples/guides/coap
--- ---
import FileTree from '@components/FileTree.astro';
CoAP (Constrained Application Protocol) is a protocol to implement REST APIs CoAP (Constrained Application Protocol) is a protocol to implement REST APIs
for constrained devices and networks. for constrained devices and networks.
It is designed for IoT applications and is similar to HTTP but much lighter. 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: Create a new directory for your project:
```text <FileTree>
coap-hello-server
├── Makefile - coap-hello-server
└── main.c - Makefile
``` - main.c
</FileTree>
### Step 2: Create the Makefile ### 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: Create a new directory for your project:
```text <FileTree>
coap-hello-client
├── Makefile - coap-hello-client
└── main.c - Makefile
``` - main.c
</FileTree>
### Step 2: Create the Makefile ### Step 2: Create the Makefile

7
doc/starlight/src/components/FileTree.astro Normal file
View File

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

2
doc/starlight/src/pages/changelog.astro
View File

@ -1,6 +1,6 @@
--- ---
import StarlightPage from "@astrojs/starlight/components/StarlightPage.astro"; 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"; import { getCollection } from "astro:content";
const changelog = await getCollection("changelog"); const changelog = await getCollection("changelog");