-
Notifications
You must be signed in to change notification settings - Fork 1.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Properly document each arch, SoC family and board #2409
Comments
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. |
Yes, it is probably better to do so.
Great, thanks.
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. |
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. 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.
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. |
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.
Yes, that is in:
but I think we should simply replace that as it gives mostly historical data which is already out of date in most cases. |
I find the three top-level sections option better. I think it would be easier to surf and find information.
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. |
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 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 Do you think this approach is OK? The only other way I see is to manually create this hierarchy by writing a |
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 ( |
@Ouss4 @btashton @xiaoxiang781216 Opinions? |
@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.
This way we will get the board name |
You mean top-level sections? (like sidebar entries?) I think that when we include all supported archs it will get too crowded. |
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. |
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? |
@v01d That is perfect! Could you please submit it? So we will use it as base for other boards. |
Yes the NOTICE file needs to be updated for these bundled binaries see We should also be very careful about keeping the images we use small if possible so we do not blow up the repository size. |
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. |
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:
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.
The text was updated successfully, but these errors were encountered: