doc/guide: Introduce a Guide Site

doc/guides: How to Doc

fix: add starlight to base makefile

Author: AnnsAnns

.github/workflows/deploy_docs.yml

@@ -0,0 +1,33 @@
+name: Build Docs
+
+on:
+    push:
+        branches:
+            - master
+        paths:
+            - 'doc/guides/**'
+            - 'doc/starlight/**'
+
+jobs:
+    build-docs:
+        runs-on: ubuntu-latest
+        defaults:
+            run:
+                working-directory: doc/starlight
+        steps:
+          - name: Checkout repository
+            uses: actions/checkout@v4
+          - name: Set up Node.js
+            uses: actions/setup-node@v4
+          - name: Build documentation
+            run: make build
+            # This step will probably need to be changed to use the actual service RIOT is using
+            # This makes it more convenient to deploy while still in development though
+          - name: Deploy documentation
+            uses: peaceiris/actions-gh-pages@v3
+            with:
+                github_token: ${{ secrets.GITHUB_TOKEN }}
+                publish_dir: doc/starlight/dist
+                publish_branch: gh-pages
+                cname: guide.riot-os.org
+                commit_message: "Deploy documentation"

Makefile

@@ -1,6 +1,6 @@
 .all:
 
-.PHONY: all doc doc-man doc-latex docclean print-versions welcome
+.PHONY: all doc doc-man doc-latex docclean doc-starlight print-versions welcome
 
 all: welcome
 	@echo ""
@@ -12,8 +12,12 @@ doc doc-man doc-latex doc-ci:
 		--output-md doc/doxygen/src/feature_list.md
 	"$(MAKE)" -C doc/doxygen $@
 
+doc-starlight:
+	"$(MAKE)" -C doc/starlight dev
+
 docclean:
 	"$(MAKE)" -BC doc/doxygen clean
+	"$(MAKE)" -C doc/starlight clean
 
 pkg-clean:
 	@echo "Cleaning all package sources"

dist/tools/ci/static_tests.sh

@@ -131,6 +131,7 @@ run ./dist/tools/codespell/check.sh
 run ./dist/tools/cargo-checks/check.sh
 run ./dist/tools/examples_check/check_has_readme.sh
 run ./dist/tools/examples_check/check_in_readme.sh
+run ./dist/tools/code_in_guides_check/check_for_code.sh
 if [ -z "${GITHUB_RUN_ID}" ]; then
     run ./dist/tools/uncrustify/uncrustify.sh --check
 else

dist/tools/code_in_guides_check/check_for_code.sh

@@ -0,0 +1,101 @@
+#!/bin/bash
+# This script checks if the code blocks in markdown files under the guides directory
+# are present in the corresponding source files. It looks for code blocks marked with
+# ```c and checks if the code exists in the source files defined by the code_folder
+# variable in the markdown file. If the code block is not found, it will print an error
+# message and exit with a non-zero status.
+
+# Define the guides directory
+BASE_DIR="$(git rev-parse --show-toplevel)"
+GUIDES_DIR="$BASE_DIR/doc/guides"
+
+# Check if directory exists
+if [ ! -d "$GUIDES_DIR" ]; then
+    echo "Error: Guides directory not found at $GUIDES_DIR"
+    exit 1
+fi
+
+exit_code=0
+
+# Parses code blocks from within a file
+# Args: $1 -> Line number of the code block
+#       $2 -> The file path
+# Returns:
+#       0 -> On found or skipped block
+#       1 -> Not found
+parse_code_block() {
+    start_line=$1
+    file_path=$2
+    # Check whether there is a <!--skip ci--> comment in the line before the code block
+    skip_ci=$(sed -n "$((start_line - 1))p" "$file_path" | grep -c '<!--skip ci-->')
+    if [ "$skip_ci" -gt 0 ]; then
+        echo "  ✔️ Line $start_line: Code block is skipped due to <!--skip ci--> comment"
+        return 0
+    fi
+
+    # Extract the code block content until the ending ```
+    code_block=$(awk -v start="$start_line" 'NR>start{if(/^```$/){exit}; print}' "$file_path")
+
+    # Check if this code exists in any file in the source directory
+    found=0
+    for src_file in "$SOURCE_DIR"/*; do
+        # Skip if not a regular file
+        [ -f "$src_file" ] || continue
+
+        # Read the file content
+        src_content=$(cat "$src_file")
+
+        # Check if the code block exists in the current source file
+        if [[ "$src_content" == *"$code_block"* ]]; then
+            found=1
+            echo "  ✔️ Found Line $start_line in $(basename "$src_file")"
+            break
+        fi
+    done
+
+    if [ $found -eq 0 ]; then
+        echo "  ❌ Line $start_line: Code block not found in any source file"
+        return 1
+    fi
+}
+
+markdown_files=$(find "$GUIDES_DIR" -type f \( -name "*.md" -o -name "*.mdx" \))
+
+# Find and process all .md and .mdx files
+for file in $markdown_files; do
+    echo "🧐 Processing file: $file"
+
+    # Check if there is a code_folder defined in the markdown file
+    code_folder=$(grep -oP -m1 'code_folder:\s*\K.+' "$file")
+    if [ -z "$code_folder" ]; then
+        echo "  ✔️ File does not specify code_folder, skipping ..."
+        continue
+    fi
+    SOURCE_DIR="$BASE_DIR/$code_folder"
+
+    echo "🔍 Looking for code in $SOURCE_DIR"
+
+    # Get all code block start lines
+    code_block_starts=$(grep -n '```[cC]' "$file" | cut -d':' -f1)
+
+    if [ -z "$code_block_starts" ]; then
+        echo "  ❌ No code blocks found in this file even though code_folder was specified."
+        exit_code=1
+    fi
+
+    # Process each code block
+    for start_line in $code_block_starts; do
+        parse_code_block "$start_line" "$file"
+        if [ "$?" -eq "1" ]; then
+            exit_code=1
+        fi
+    done
+done
+
+if [ $exit_code -eq 0 ]; then
+    echo "👍 All code blocks found in the source files."
+else
+    echo "👎 Some code blocks were not found in the source files. See the output above."
+fi
+
+exit $exit_code

doc/guides/build-system/advanced_build_system_tricks.md

@@ -0,0 +1,64 @@
+---
+title: Advanced Build System Tricks
+description: This page describes some build systems tricks that can help developers but are not part of the standard workflow.
+---
+
+This page describes some build systems tricks that can help developers but are not part of the standard workflow.
+
+They are low level commands that should not be taken as part of a stable API but better have a documentation than only having a description in the build system code.
+
+## Customize the build system
+
+- `RIOT_MAKEFILES_GLOBAL_PRE`: files parsed before the body of `$RIOTBASE/Makefile.include`
+- `RIOT_MAKEFILES_GLOBAL_POST`: files parsed after the body of `$RIOTBASE/Makefile.include`
+
+The variables are a list of files that will be included by `$RIOTBASE/Makefile.include`. They will be handled as relative to the application directory if the path is relative.
+
+## Usage
+
+You can configure your own files that will be parsed by the build system main `Makefile.include` file before or after its main body, examples usages can be:
+
+- Globally overwrite a variable, like `TERMPROG`
+- Specify a hard written `PORT` / `DEBUG_ADAPTER_ID` for some BOARD values
+- Define your custom targets
+- Override default targets
+
+## Analyze dependency resolution
+
+When refactoring dependency handling or modifying variables used for dependency resolution, one may want to evaluate the impact on the existing applications. This describe some debug targets to dump variables used during dependency resolution.
+
+To analyze one board and application run the following commands in an application directory.
+
+Generate the variables dump with the normal dependency resolution to a `dependencies_info_board_name` file:
+
+```sh
+BOARD=board_name make dependency-debug
+```
+
+Or with the "quick" version used by murdock to know supported boards (this is an incomplete resolution, details in `makefiles/dependencies_debug.inc.mk`) to a `dependencies_info-boards-supported_board_name` file:
+
+```sh
+BOARDS=board_name DEPENDENCY_DEBUG=1 make info-boards-supported
+```
+
+For more configuration and usage details, see in the file defining the targets `makefiles/dependencies_debug.inc.mk`.
+
+To do a repository wide analysis, you can use the script `dist/tools/buildsystem_sanity_check/save_all_dependencies_resolution_variables.sh` that will generate the output for all boards and applications. It currently take around 2 hours on an 8 cores machine with ssd.
+
+## Generate Makefile.ci content
+
+Most applications and tests include a `Makefile.ci` to indicate which boards cannot compile the application or test. The content for these files can be generated via the script in:
+
+```sh
+make -C $APPLICATION_DIRECTORY generate-Makefile.ci
+```
+
+This will compile and link the application for every board available and record the result in the Makefile.ci. This requires the toolchain for every target to be available. The target supports using docker via the `BUILD_IN_DOCKER=1` variable.
+
+## Out of Tree Cache Directory
+
+By exporting the `BUILD_DIR` environment variable, a custom build / clone cache directory can be created. This can be particularly useful when working with multiple git work trees or clones of the RIOT repository.
+
+## RIOT-aware Completion in zsh
+
+For zsh users a RIOT-aware completion is provided in `dist/tools/zsh-completion`. Refer to the `README.md` in there for more details and installation instructions.

doc/guides/build-system/build-in-docker.md

@@ -0,0 +1,128 @@
+---
+title: Build in Docker
+description: Building RIOT in a Docker container
+---
+
+Some parts of RIOT's build process can be performed inside a Docker container,
+which comes with the necessary compilers and toolchains and is fully managed by
+the build system. It can be enabled by passing `BUILD_IN_DOCKER=1` to make.
+
+```shell
+$ BUILD_IN_DOCKER=1 make
+```
+
+If your user does not have permissions to access the Docker daemon:
+
+```shell
+$ BUILD_IN_DOCKER=1 DOCKER="sudo docker" make
+```
+
+to always use Docker for building, set `BUILD_IN_DOCKER=1` (and if necessary
+`DOCKER="sudo docker"`) in the environment:
+
+```console
+$ export BUILD_IN_DOCKER=1
+```
+
+## Targets ran in Docker: DOCKER_MAKECMDGOALS_POSSIBLE
+
+Currently only build related targets are ran in the docker container, the exact
+list is under `DOCKER_MAKECMDGOALS_POSSIBLE` variable.
+
+## Environment Variables: DOCKER_ENV_VARS
+
+When building in docker one might want for the command ran in docker to inherit
+variables that might have been set in the command line. e.g.:
+
+```shell
+BOARD=samr21-xpro USEMODULE=xtimer make -C examples/hello-world
+```
+
+In `docker.ink.mk` the origin of a variable listed in `DOCKER_ENV_VARS` is checked
+and if the origin is `environment` or `command` (for make command-line argument)
+then those variables will be  passed to the docker container.
+
+You can also set in `DOCKER_ENV_VARS` in the environment to add variables to the
+list, e.g.:
+
+```shell
+DOCKER_ENV_VARS=BEER_TYPE BEER_TYPE="imperial stout" BUILD_IN_DOCKER=1 make -C examples/hello-world/
+docker run --rm -t -u "$(id -u)" \
+    ...
+    -e 'BEER_TYPE=imperial stout' \
+    -w '/data/riotbuild/riotbase/examples/hello-world/' \
+    'riot/riotbuild:latest' make
+```
+
+Your application Makefile can also extend `DOCKER_ENV_VARS`.
+
+### Directly Define Environment Variables: DOCKER_ENVIRONMENT_CMDLINE
+
+`DOCKER_ENVIRONMENT_CMDLINE` can be used to add variables directly to the environment
+but will need to be prefixed with `-e` (see [option-summary]).
+
+e.g.:
+
+```
+DOCKER_ENVIRONMENT_CMDLINE='-e BEER_TYPE="imperial stout"' BUILD_IN_DOCKER=1 make -C examples/hello-world/
+docker run --rm -t -u "$(id -u)" \
+    ...
+    -e 'BEER_TYPE=imperial stout' \
+    -w '/data/riotbuild/riotbase/examples/hello-world/' \
+    'riot/riotbuild:latest' make
+```
+
+## Command Line Variables: DOCKER_OVERRIDE_CMDLINE
+
+Command line arguments are variables that are passed after `make` e.g.
+`make target FOO=bar`, but different to environment variables a variable defined
+through the command line will take precedence over all assignments of `FOO` within
+the makefile (same effect as adding `-e` for environment variables, see
+[option-summary] for more details.
+
+To pass variables overriding the command-line to docker `DOCKER_OVERRIDE_CMDLINE`
+may be used:
+
+```shell
+DOCKER_OVERRIDE_CMDLINE="BEER_TYPE='imperial stout'" BUILD_IN_DOCKER=1 make -C examples/hello-world/ RIOT_CI_BUILD=1
+Launching build container using image "riot/riotbuild:latest".
+sudo docker run --rm -t -u "$(id -u)" \
+    ...
+    -w '/data/riotbuild/riotbase/examples/hello-world/' \
+    'riot/riotbuild:latest' make  BEER_TYPE='imperial stout' 'RIOT_CI_BUILD=1'
+```
+
+### Redefined or Overridden Variables: DOCKER_ENV_VARS_ALWAYS
+
+There is a corner case for the handling of `DOCKER_ENV_VARS`. If a variable is
+redefined (`+=`, `=`, `:=`) or overridden then the origin of the variable will be changed
+to `file` and there is no way of detecting in Make how it was set.
+
+If this happens after `docker.ink.mk` this is not an issue, but for all variables
+susceptible to be defined in the application `Makefile` this is indeed the case.
+
+A subset of these variables, namely variables relating to dependency resolution
+are therefore unconditionally passed to docker. The complete list can be found
+under `DOCKER_ENV_VARS_ALWAYS`.
+
+#### CFLAGS
+
+CFLAGS are not automatically passed to docker because they might contain spaces,
+'"' or other characters that will require escaping. The solution is to pass it with
+`DOCKER_ENVIRONMENT_CMDLINE` and escape every character as required.
+
+e.g: if wanting to override STRING_WITH_SPACES
+
+```
+# normal build
+CFLAGS=-DSTRING_WITH_SPACES='\"with space\" make
+# in docker
+DOCKER_ENVIRONMENT_CMDLINE='-e CFLAGS=-DSTRING_WITH_SPACES=\'\\\"with\ space\\\"\'' \
+  BUILD_IN_DOCKER=1 make
+```
+
+Alternatively, it is often easier to define the CFLAGS in the Makefile which gets
+evaluated inside the Docker image again), conditional on a less complex environment
+variable that gets added to `DOCKER_ENV_VARS` in the Makefile.
+
+[option-summary]: https://www.gnu.org/software/make/manual/html_node/Options-Summary.html