Merge pull request #21729 from LasseRosenow/fix-guides-code-blocks

doc/guides: Fix code block indentation and improve board file structure ASCII art

Author: crasbe

doc/guides/advanced_tutorials/creating_modules.md

@@ -114,47 +114,47 @@ 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
 
-  ```makefile
-  ifneq (,$(filter foo_bar,$(USEMODULE)))
-    SRC += foo_bar.c
-  endif
-  ```
+```makefile
+ifneq (,$(filter foo_bar,$(USEMODULE)))
+  SRC += foo_bar.c
+endif
+```
 
 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
-  MODULE := foo_bar
+```makefile
+# make all code end up in "foo_bar.a", this can be any name
+MODULE := foo_bar
 
-  # ensure that "foo_ham" or "bar_foo_ham" builds "foo_ham.c".
-  BASE_MODULE := foo
+# ensure that "foo_ham" or "bar_foo_ham" builds "foo_ham.c".
+BASE_MODULE := foo
 
-  # list of source files that are not SUBMODULES
-  SRC := spam.c
+# list of source files that are not SUBMODULES
+SRC := spam.c
 
-  # enable submodules by setting SUBMODULES = 1
-  SUBMODULES = 1
-  ```
+# enable submodules by setting SUBMODULES = 1
+SUBMODULES = 1
+```
 
 When using `SUBMODULES` in a `MODULE` all `SRC` file excluded from `foo/Makefile`
 will be considered `SUBMODULES`. In the example above `ham.c` and `eggs.c`.

doc/guides/advanced_tutorials/porting_boards.md

@@ -32,19 +32,19 @@ 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
@@ -170,7 +170,7 @@ The default serial port configuration is provided by
 `makefiles/tools/serial.inc.mk` and defines the following values for the serial
 port (depending on the host OS):
 
-```
+```makefile
 PORT_LINUX ?= /dev/ttyACM0
 PORT_DARWIN ?= $(firstword $(sort $(wildcard /dev/tty.usbmodem*)))
 ```
@@ -201,6 +201,10 @@ It can be measured by running `tests/sys/ztimer_overhead` on your board, i.e:
 
 ```bash
 $ BOARD=my-new-board make -C tests/sys/ztimer_overhead flash term
+```
+
+This should give the following output:
+```
 main(): This is RIOT!
 ZTIMER_USEC auto_adjust params:
     ZTIMER_USEC->adjust_set = xx
@@ -346,23 +350,23 @@ 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
@@ -378,7 +382,7 @@ In this case some special considerations must be taken with the makefiles:
     one):
 
 ```makefile
-      DIRS += $(RIOTBOARD)/foo-parent
+DIRS += $(RIOTBOARD)/foo-parent
 ```
 
 - `Makefile.include`

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

@@ -63,7 +63,7 @@ but will need to be prefixed with `-e` (see [option-summary]).
 
 e.g.:
 
-```
+```shell
 DOCKER_ENVIRONMENT_CMDLINE='-e BEER_TYPE="imperial stout"' BUILD_IN_DOCKER=1 make -C examples/basic/hello-world/
 docker run --rm -t -u "$(id -u)" \
     ...
@@ -105,20 +105,24 @@ 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
 
 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
+
+```shell
+CFLAGS='-DSTRING_WITH_SPACES="\"with space\""' make
 ```
-# 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
+
+#### In Docker
+
+```shell
+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

doc/guides/build-system/build_system_basics.md

@@ -22,9 +22,10 @@ The fact that many `FEATURES` translate directly into a `MODULE` is only by
 convenience.
 
 e.g.
-
-    # all periph features correspond to a periph submodule
-    USEMODULE += $(filter periph_%,$(FEATURES_USED))
+```makefile
+# all periph features correspond to a periph submodule
+USEMODULE += $(filter periph_%,$(FEATURES_USED))
+```
 
 ### Providing a FEATURE
 
@@ -136,7 +137,7 @@ regarding these subjects.
 
 ## Avoid Unnecessary Export
 
-```
+```makefile
 export OUTPUT = $(shell some-command)
 ```
 
@@ -158,7 +159,7 @@ This is why global variables need clear documentation.
 
 ### Recursively Expanded Variable
 
-```
+```makefile
 OUTPUT = $(shell some-command $(ANOTHER_VARIABLE))
 ```
 
@@ -177,7 +178,7 @@ OUTPUT = $(shell some-command $(ANOTHER_VARIABLE))
 
 ### Simply Expanded Variable
 
-```
+```makefile
 OUTPUT := $(shell some-command $(ANOTHER_VARIABLE))
 ```
 
@@ -195,7 +196,7 @@ OUTPUT := $(shell some-command $(ANOTHER_VARIABLE))
 
 ### Memoized
 
-```
+```makefile
 OUTPUT = $(call memoized,OUTPUT,$(shell some-command))
 ```
 

doc/guides/build-system/debugging_aids.md

@@ -16,7 +16,8 @@ undefined behavior (UB).
 E.g., the following code might trigger UB for some parameters:
 
 ```c
-void test(int foo) {
+void test(int foo)
+{
     return (foo << 24);
 }
 ```