Hello,
There is this PR 1 about moving all board documentation (specs, how to flash, etc) from the wiki to Doxygen, which I would like to know your thoughts since it’s a major change in the RIOT documentation.
As stated there, the main motivation is to help developers keep the documentation up to date, and also provide the same entry point for board related stuff. Board content was not modified during the process, but some broken links were fixed
Doxygen is probably not the best for non-API documentation, and there are some on going discussions:
-
Board documentation would be in boards/<board_name>/doc.txt in Markdown format, but with C style comments as seen here 2. The way Doxygen processes .md files is different and somehow breaks the left navigation bar.
-
There’s now mixed logic parts (definitions, periph config) with non logic parts (hardware TODOs, how to flash, etc).
Also, there are some offline comments about the need of unifying the board documentation (e.g all boards should have at least Specs, periphs, etc. which is not present in the current wiki). This goes beyond the scope of this PR but could give some clues about how to proceed.
There are some PRs 3 that depend on the resolution of this, so I wanted to ask your opinion/comments on the discussions above. Is this concept OK to be merged and keep improving later?
I appreciate all comments about this. Cheers,
José