[riot-notifications] [RIOT-OS/RIOT] [RFC-WIP] docs: move wiki's Board documentation to Doxygen (#8508)

Alexandre Abadie notifications at github.com
Fri Feb 2 13:11:04 CET 2018


I like the idea of moving board documentation from the wiki to the code base.

Unfortunately, I'm not convinced by the proposed approach or maybe I misunderstood it.
* This breaks the existing board module already used in doxygen. How do you link a board to the existing `boards` module group ?
* I don't think adding a new menu entry in the top menu makes sense, just reuse the existing doxygen `boards`group

For me, the actual approach is moving the existing problem, e.g duplicated board documentation, from one place (the wiki) to another (new markdown files in the code base).

I would rather add a `doc.txt` file in each board directory see the `feather-m0` or some `arduino-mkr` for example. The doc.txt can contain Markdown compatible documentation.
You can also use doxygen commands (`@ref`, `@see`, etc) to nicely link things (CPU, boards, drivers) in the documentation.

Regarding the link to images, there are 2 possibilities (as already mentioned):
* put hyperlinks to external resources: this is already the case for some boards, it's the simplest solution but it may fail if no connection to the web or the url changed
* put images in another place that we manage. For this solution, I think the wiki is the best place since it's already a git repo (https://github.com/RIOT-OS/RIOT.wiki.git or git at github.com:RIOT-OS/RIOT.wiki.git). This option might be better suited for custom images (pinout mappings, etc).

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/RIOT-OS/RIOT/pull/8508#issuecomment-362570205
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.riot-os.org/pipermail/notifications/attachments/20180202/cd94e0e7/attachment-0001.html>


More information about the notifications mailing list