[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:
-------------- 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