diff --git a/dist/tools/buildsystem_sanity_check/check.sh b/dist/tools/buildsystem_sanity_check/check.sh index de90c179b91f..b9c2e827da28 100755 --- a/dist/tools/buildsystem_sanity_check/check.sh +++ b/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') diff --git a/doc/guides/advanced_tutorials/creating_application.md b/doc/guides/advanced_tutorials/creating_application.mdx similarity index 97% rename from doc/guides/advanced_tutorials/creating_application.md rename to doc/guides/advanced_tutorials/creating_application.mdx index 2dca9b2e12cc..88a9698c239c 100644 --- a/doc/guides/advanced_tutorials/creating_application.md +++ b/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 -``` + + +- apps + - my_app + - Makefile +- boards + - my_board/ +- modules + - my_module + - include + -my_module.h + - Makefile + - Makefile.include + - my_module.c +- RIOT/ + + In this example tree, the `apps` directory contains a collection of applications for the project. The modules directory could contain extra modules for the diff --git a/doc/guides/advanced_tutorials/creating_modules.md b/doc/guides/advanced_tutorials/creating_modules.mdx similarity index 92% rename from doc/guides/advanced_tutorials/creating_modules.md rename to doc/guides/advanced_tutorials/creating_modules.mdx index 221f19468f5e..9f87d15110f9 100644 --- a/doc/guides/advanced_tutorials/creating_modules.md +++ b/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 -``` + + +- foo + - foo_bar.c + - foo.c + - Makefile + + 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 -``` + + + +- foo + - spam.c + - ham.c + - eggs.c + - Makefile + + ```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. diff --git a/doc/guides/advanced_tutorials/porting_boards.md b/doc/guides/advanced_tutorials/porting_boards.mdx similarity index 94% rename from doc/guides/advanced_tutorials/porting_boards.md rename to doc/guides/advanced_tutorials/porting_boards.mdx index 50a1777d083c..ae32d0ddff32 100644 --- a/doc/guides/advanced_tutorials/porting_boards.md +++ b/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 -``` + + +- board-foo + - dist + - scripts/ + - board.c + - doc.md + - include + - periph_conf.h + - board.h + - gpio_params.h + - Makefile + - Makefile.dep + - Makefile.features + - Makefile.include + + ### 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 -``` + + +- 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 + + 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 -``` + + +- 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 + + If the external `BOARD` is very similar to a `BOARD` already present in `RIOTBOARD`, the external `BOARD` (`board-foo`) can inherit from that diff --git a/doc/guides/c_tutorials/coap.md b/doc/guides/c_tutorials/coap.mdx similarity index 97% rename from doc/guides/c_tutorials/coap.md rename to doc/guides/c_tutorials/coap.mdx index d625de0c1d20..4c454b92a944 100644 --- a/doc/guides/c_tutorials/coap.md +++ b/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 -``` + + +- coap-hello-server + - Makefile + - main.c + + ### 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 -``` + + +- coap-hello-client + - Makefile + - main.c + + ### Step 2: Create the Makefile diff --git a/doc/starlight/astro.config.mjs b/doc/starlight/astro.config.ts similarity index 99% rename from doc/starlight/astro.config.mjs rename to doc/starlight/astro.config.ts index 7ec7954e3cf7..d8b3f45baca6 100644 --- a/doc/starlight/astro.config.mjs +++ b/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"; diff --git a/doc/starlight/src/components/FileTree.astro b/doc/starlight/src/components/FileTree.astro new file mode 100644 index 000000000000..e69b9341ab01 --- /dev/null +++ b/doc/starlight/src/components/FileTree.astro @@ -0,0 +1,7 @@ +--- +import { FileTree as StarlightFileTree } from "@astrojs/starlight/components"; +--- + + + + diff --git a/doc/starlight/src/pages/changelog.astro b/doc/starlight/src/pages/changelog.astro index cd1429cb7540..44261ce21274 100644 --- a/doc/starlight/src/pages/changelog.astro +++ b/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");