kaspar/RIOT
1
0
Fork 0
mirror of https://github.com/RIOT-OS/RIOT.git synced 2025-12-14 17:13: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
---
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

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

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

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

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 { LinkButton, LinkCard } from "@astrojs/starlight/components";
import { LinkButton, LinkCard, FileTree } from "@astrojs/starlight/components";
import { getCollection } from "astro:content";
const changelog = await getCollection("changelog");