RFC: Board documentation


Nashif, Anas
 

Hi,

Sometime a go we used to have the board documentation in the tree, since then we move those to the wiki and right now there is some kind of disconnect between the boards we have in the source tree and whatever is on the wiki.

Similar to the sample documentation RFC from yesterday, here is one for board documentation. The TSC has decided to move board documentation back to the git repo and have the board documentation reside in the board directory. The idea is to have board act as drop-ins with all needed information, including documentation.

The documentation for a board shall have the following structure (feedback welcome):

[Board Name]
################

Overview
========
[A short description about the board, its main features and availability]

Hardware
=========
[General Hardware information]

Supported Features
---------------------------
[List of supported features and level of support in Zephyr]

Pin Map
------------
[Tables describing the board PINs and how they are configured and can be used to connect external components]

Programming and Debugging
=========================

Flashing
-----------
[How to use this board with Zephyr and how to flash a Zephyr binary on this device]


Debugging
---------------
[ How to debug this board]


References
=========
[ Links to external references such as datasheets or additional documentation]


and should be placed in the relevant board directory under doc/, so for example, for the quark d200 devboard, this will be in:

boards/x86/quark_d2000_crb/doc/quark_d2000_crb.rst

This will then be picked up by the top boards.rst under boards/ and placed in the online documentation at the right spot. There will be no need to include it in any other index files.

The relevant Gerrit that adds the first board back and integrates it into the system is here: https://gerrit.zephyrproject.org/r/#/c/9703/


Feedback welcome.

Anas

Join devel@lists.zephyrproject.org to automatically receive all group messages.