[riot-devel] Board documentation in Doxygen

Jose Alamos jialamos at uc.cl
Mon Apr 16 10:34:15 CEST 2018


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é

[1]: https://github.com/RIOT-OS/RIOT/pull/8516
[2]:
https://github.com/RIOT-OS/RIOT/pull/8516/files#diff-52f923e555f1076b7f5e7ecc92e61a37
[3]: https://github.com/RIOT-OS/RIOT/pull/8651
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.riot-os.org/pipermail/devel/attachments/20180416/44372c3f/attachment.html>


More information about the devel mailing list