v01d commented on issue #2409: URL: https://github.com/apache/incubator-nuttx/issues/2409#issuecomment-774107175
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. ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected]
