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

Merge pull request #21257 from crasbe/pr/porting_boards_new

Browse Source 
doc/porting-boards: Change example doc.txt to doc.md
This commit is contained in:
mguetschow 2025-03-03 13:04:19 +00:00 committed by GitHub
commit e545642ef1
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 16 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
doc/doxygen/src/porting-boards.md
View File

@ -29,7 +29,7 @@ makefiles. Usually a `BOARD` directory has the following structure
|----dist/ |----dist/
|----scripts |----scripts
|----board.c |----board.c
|----doc.txt |----doc.md
|----include/ |----include/
|----periph_conf.h |----periph_conf.h
|----board.h |----board.h
@ -215,7 +215,7 @@ Alternatively, the pseudomodule @ref pseudomodule_ztimer_auto_adjust can be used
in an application to enable automatic timer offset compensation at board startup. in an application to enable automatic timer offset compensation at board startup.
This however incurs overhead both in the text segment and at bootup time. This however incurs overhead both in the text segment and at bootup time.
## doc.txt {#board-doc} ## doc.md {#board-doc}
Although not explicitly needed, if upstreamed and as a general good Although not explicitly needed, if upstreamed and as a general good
practice, this file holds all `BOARD` documentation. This can include practice, this file holds all `BOARD` documentation. This can include
@ -225,8 +225,7 @@ The documentation must be under the proper doxygen group, you can compile the
documentation by calling `make doc` and then open the generated html file on documentation by calling `make doc` and then open the generated html file on
any browser. any browser.
``` ```md
/**
@defgroup boards_foo FooBoard @defgroup boards_foo FooBoard
@ingroup boards @ingroup boards
@brief Support for the foo board @brief Support for the foo board
@ -234,7 +233,7 @@ any browser.
### User Interface ### User Interface
.... ...
### Using UART ### Using UART
@ -243,8 +242,18 @@ any browser.
### Flashing the device ### Flashing the device
... ...
```
*/ Previously documentation was contained in `doc.txt` files with C-style comment
blocks. This style has been deprecated in favor of using `doc.md` files in
Markdown format, which eliminates formatting and interpretation issues.
Old style files will continually be replaced by the new format.
Up to version `0.9.2` the [riotgen](https://pypi.org/project/riotgen/) tool
will generate `doc.txt` files instead of `doc.md` files. You can upgrade it to
the latest version with
```sh
pip install --upgrade riotgen
``` ```
# Helper tools # Helper tools
@ -341,7 +350,7 @@ specify multiple directories separated by spaces.
|----dist/ |----dist/
|----scripts |----scripts
|----board.c |----board.c
|----doc.txt |----doc.md
|----include/ |----include/
|----periph_conf.h |----periph_conf.h
|----board.h |----board.h