I really like having the (board) documentation as part of repository!

HTML comments for family matching? Any ideas?

Not sure if feasible, but would it be possible to retrieve this information from the general Makefiles? If the name of the doc page matches the board's name, then it should be possible to inspect the Makefile and take all the information from there?

I did not look at the code, so I don't know if you already did, but it should be possible via the semi-hidden wiki git repository to extract all the board markdown from the wiki and import it into these files.
Regarding images, maybe we could create a separate repo on the RIOT-OS organisation that can be used as a storage for the images. It's not ideal though, so there might be much better solutions

Not sure if feasible, but would it be possible to retrieve this information from the general Makefiles? If the name of the doc page matches the board's name, then it should be possible to inspect the Makefile and take all the information from there?

@basilfx Yes, it's somehow possible. Since the script detects all boards with a doc folder inside, it would be possible to retrieve CPU family with "make info-" like commands. The only issue now is usually this commands are activated inside an app.

I did not look at the code, so I don't know if you already did, but it should be possible via the semi-hidden wiki git repository to extract all the board markdown from the wiki and import it into these files.

@gebart Yes, indeed.

Regarding images, maybe we could create a separate repo on the RIOT-OS organisation that can be used as a storage for the images. It's not ideal though, so there might be much better solutions

Yes, I think it's a good approach. As far as I see, in the current state there are several wiki pages pointing to external resources. I'm not sure if it's the same for all boards

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 boardsgroup

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 [email protected]:RIOT-OS/RIOT.wiki.git). This option might be better suited for custom images (pinout mappings, etc).

@aabadie:

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.

I tend to like the idea, but is it possible to somehow have the same structure as the wiki with this approach? E.g, append the SAMR21 Board entry to the wiki entry and have all the information in the same page?

I don't think adding a new menu entry in the top menu makes sense, just reuse the existing doxygen boardsgroup

IMO Supported Boards is more than a single entry in the Modules group. E.g the openthread.io and contiki-os.org sites have both an exposed entry to the supported platform.

Not sure if should be a link to the Boards group, but I think it's important to have at least a page with all info related to Supported Boards.

is it possible to somehow have the same structure as the wiki with this approach? E.g, append the SAMR21 Board entry to the wiki entry and have all the information in the same page?

Yes, it's just a matter of changing the groups hierarchy in doxygen: boards > boards_family > boards_arm_xxx.
The question is do we want to keep this structure ?

Not sure if should be a link to the Boards group, but I think it's important to have at least a page with all info related to Supported Boards.

We already have this http://doc.riot-os.org/group__boards.html
Maybe the boards group documentation could be improved with additional links (how to build, cpus, etc).

I tend to like the idea, but is it possible to somehow have the same structure as the wiki with this approach? E.g, append the SAMR21 Board entry to the wiki entry and have all the information in the same page?

Just checked the files and yes, seems to be possible. I will try to go that way

The question is do we want to keep this structure ?

Not sure if grouping them by family name gives too much value to doc consumers. And also, IMO just adds complexity.
I would live it as the current Board entry in Doxygen

@aabadie btw thx for the feedback

Just a side comment regarding shell scripts. I'm wondering if it won't be simpler to use Python for the migration script.
Following the idea, we could even imagine a python script that generate an empty structure for a board support (or a driver) with the right files/directories and copyright headers, etc

Just a side comment regarding shell scripts. I'm wondering if it won't be simpler to use Python for the migration script.
Following the idea, we could even imagine a python script that generate an empty structure for a board support (or a driver) with the right files/directories and copyright headers, etc

I like the idea, like Django's djando-admin.py startproject or djando-admin.py startapp. Could be used for almost all RIOT componentes (apps, tests, drivers, sys, etc).

Could be used for almost all RIOT components (apps, tests, drivers, sys, etc).

Yes. Using Python could help since this will mainly concern string managements and Python is very good for that.

I will close this one in favor of #8516.