Properly document each arch, SoC family and board

[protobits]

I've been thinking for some time on how to better organize and document all the hardware that NuttX supports. My idea is to have three levels of "supported X" sections in Documentation:

1. Supported Architectures
2. Supported SoCs
3. Supported Boards

For (1) it would document how things are implemented in arch/arm (and each arm version), arch/risc-v, etc. Not very familiar with those parts but most likely something things are worth explaining. For (2) it would document how each SoC family (stm32, stm32l4, nrf52, etc) exposes and implements hardware functionality on NuttX. For (3) I think it would be useful to document each board similarly to how Zephyr does. For example: https://docs.zephyrproject.org/latest/boards/arm/atsamd21_xpro/doc/index.html This means a picture of the board, description of on-board devices (possibly indicating either supported or not supported features) and maybe some examples of particular configurations demonstrating some interesting ability of the board (ie: LVGL running on embedded display, etc).

For both (1) and (2) there are surely quite a lot of APIs to document which would also help in understanding how to support new chips/boards. These are also good places to document required toolchains.

For (3) we currently have board READMEs, which vary in quality/techical detail. Many were copied from other READMEs and there's a lot of repetition explaining how to do basic NuttX things or things that apply to all boards with the SoC (an example of something to document at (2)). So I'm not sure how much we could take advantage of those READMEs but of course they would be a starting point for (3).

What I'm unsure about is where to place these RST documents. The normal thing would be to continue documenting all of this under Documentation/. But I wonder if someone who changes something for a board, SoC or architecture will really be aware of the documentation which need updating if it is placed elsewhere. Of course just placing the file "close" to the relevant sources is no guarantee either. The downside of doing so is that board pictures for example would probably have to be stored next to sources (probably not a good idea). What do you think about this?

I know all of this is a lot of documentation to write but I think it is better to have start exposing this with very basic information than to not have anything at all.

[btashton]

I think it makes sense to put these docs in the Documentation folder. I think making sure people update the docs is just something we need to get in a habit of during the review process.

Putting the docs there also makes it easier to link to shared information. I'm happy to help get some of the board documentation up to date at least for boards that I have.

We do have a lot of boards that are quite old and not available anymore, I guess we can base it on what is already there.

There is still a lot of good information in the wiki that we should also start migrating over.

[protobits]

I think it makes sense to put these docs in the Documentation folder. I think making sure people update the docs is just something we need to get in a habit of during the review process.

Yes, it is probably better to do so.

Putting the docs there also makes it easier to link to shared information. I'm happy to help get some of the board documentation up to date at least for boards that I have.

Great, thanks.

We do have a lot of boards that are quite old and not available anymore, I guess we can base it on what is already there.

There is still a lot of good information in the wiki that we should also start migrating over.

Yes, that is also something I looked over the other day. It will be challenging since it will probably involve finding good places for each piece of information and maybe creating new sections.

[Ouss4]

I think we can start by the boards (point (3)) and work our way up. Documenting everything in arch or the different chips can be daunting. At least, we can just list the devices/features that are supported.

In the old documentation, we had an HTML table that groups all the supported architectures, chips and boards and then some descriptive details where given in a section below. The boards READMEs are more for technical details, they show how to run the configs and how to overcome certain issues.

For the boards, we can group all the information in one document as suggested. We would end up with something similar to the Zephyr example.

I think making sure people update the docs is just something we need to get in a habit of during the review process.

Yes, we really need to do that. In the previous 2 releases we had to update the documents during the preparation of the release notes. That was somewhat painful as things can accumulate.

[protobits]

I think we can start by the boards (point (3)) and work our way up. Documenting everything in arch or the different chips can be daunting. At least, we can just list the devices/features that are supported.

Yes, there could be a lot to document, but we can focus on the important things first. I would create a skeleton for (1) and (2) and at least begin to document nRF52 in (2) which I'm most familiar with. What I'm not sure is if we should create a "Supported Hardware" section which starts with a list of (1), and then for each item in (1) have all items in (2) and same with (3) (ie: mimicking the hierarchy of the code). The alternative is three lists, (1), (2) and (3) as top-level sections.

In the old documentation, we had an HTML table that groups all the supported architectures, chips and boards and then some descriptive details where given in a section below.

Yes, that is in:

• https://nuttx.apache.org/docs/latest/introduction/supported_platforms.html
• https://nuttx.apache.org/docs/latest/introduction/detailed_support.html

but I think we should simply replace that as it gives mostly historical data which is already out of date in most cases.

[Ouss4]

Yes, there could be a lot to document, but we can focus on the important things first. I would create a skeleton for (1) and (2) and at least begin to document nRF52 in (2) which I'm most familiar with. What I'm not sure is if we should create a "Supported Hardware" section which starts with a list of (1), and then for each item in (1) have all items in (2) and same with (3) (ie: mimicking the hierarchy of the code). The alternative is three lists, (1), (2) and (3) as top-level sections.

I find the three top-level sections option better. I think it would be easier to surf and find information.

but I think we should simply replace that as it gives mostly historical data which is already out of date in most cases.

I agree. Some of what's written there is still relevant and we can still leverage from it. But for the most part, it should be replaced by this new organisation.

[protobits]

I decided to start this, in the hopes that we can get better organized arch/board documentation. I documented nRF52 arch and will document the nRF52832-MDK board as a starting point. I also started some stubs for ESP32/BL602 to test how the hierarchy looks for boards on other archs.

I'm currently thinking how to organize the documentation. We discussed three top-level sections but I think that gets really messy since the arch-soc-board hierarchy gets flattened. I think the best way is to mimic the organization inside boards/ as: Documentation/platforms/<arch>/<soc>/<board>, which allows to document things at their proper level with an individual index.rst (eg: platforms/arm/index.rst, platforms/arm/nrf52/index.rst, etc.).

The only thing I'm not sure how to handle is that I would like to have this three-level hierarchy visible as a ToC, but this means having the board index.rst's generate a section at the same level that of a SoC. To make this work, I had to create a "Supported Boards" section inside the soc document, which may feel a bit weird. The result is the following:

Notice that in the last screenshot the document is not visible on the sidebard as it is limited to three levels, to avoid listing too many document sections. The problem is that if I do not nest boards under a "Supported Boards" section, board entries will appear at the same level as soc document sections. Another option is to completely hide the "supported boards" section (they can still be exposed as in the first screenshot) but it will still not be visible in the sidebar.

Do you think this approach is OK? The only other way I see is to manually create this hierarchy by writing a boards/index.rst with sections and subsections for arch-soc and manually written list of links to board documents. This would make the sidebar look as expected while having a similar layout as first screenshot. I guess this could be scripted (create this .rst on the fly), but I'm not sure what's better in that case.

[protobits]

BTW, I decided to overlook for the time being that maybe we should actually have core-level and arch-variant documentation (ie: cortex-m4, archv7m). I think these could be sibling documents to the arch one (arm/cortex-m4.rst), in which there could be extra ToCs for these in arm/index.rst. But I'm not really sure if it is really important to do this right now. I think documenting SoC-level and board-level functionality first is more important.

[protobits]

@Ouss4 @btashton @xiaoxiang781216

Opinions?

[acassis]

@v01d I think the way you did in the screenshot is better. Separating by core-level and arch-variant is interesting only from technical point of view and organization. For end users it is better to have the name of the chip and the board names. Maybe instead of having a single "Supported Platforms" session we could do this way:

Supported ARM Platforms
  Nordic nRF52
    nRF52832-MDK
      Clock Configuration
      System Timer
      Regulator Control
      Peripheral Support
      BLE Support
      Supported Boards
Supported RISC-V Platforms
Supported Xtensa Platforms

This way we will get the board name

[protobits]

You mean top-level sections? (like sidebar entries?) I think that when we include all supported archs it will get too crowded. Also, note that the leaf sections are documenting a the nRF52 SoC, not the board.

[acassis]

Yes, I noticed that the leaf was the nRF52 SoC, this is why I suggested creating Supported XXXX Platform as top item, but I agree with you it could be too crowded. Maybe we could modify the system to display one more level.

[protobits]

I managed to increase depth of sidebar to five levels. As it requires expanding with the [+] it still looks OK for deeply nested sections (in fact it helps navigation). Now the first screenshot is the same, whereas the last one looks like:

The board description page is no longer "hidden" (note the sidebar):

BTW, how do we deal with licensing of images? This pinout diagram is from MakerDairy official GitHub with MIT license. Should I add the copyright notice somewhere?

[acassis]

@v01d That is perfect! Could you please submit it? So we will use it as base for other boards.

[btashton]

BTW, how do we deal with licensing of images? This pinout diagram is from MakerDairy official GitHub with MIT license. Should I add the copyright notice somewhere?

Yes the NOTICE file needs to be updated for these bundled binaries see https://www.apache.org/legal/src-headers.html#faq-media

We should also be very careful about keeping the images we use small if possible so we do not blow up the repository size.

[btashton]

I like this @v01d I think we should take this in whatever form seems reasonable and then iterate on it as we add content to it.