Documenting boards using the README's in each subdirectory (by converting them to Markdown and having them rendered somewhere) is indeed to most direct approach. Although I would say it is an intermediate solution.
I think having an explicit repo holding documentation written in something more powerful (ReStructured text, or whatever) would probably allow to get better results. In this repo a CI system could use python or whatever dependency necessary. No need to add build-dependencies to NuttX codebase for that. In that scenario, I would try to move most of the user-friendly documentation towards that repo away from the board READMEs, leaving them only with technical details that are better described there. I would still use Markdown in that case, due to how GitHub renders them. So, until something like that is done I think it would be appropriate to move all READMEs to Markdown and have them available somewhere, but as I mentioned, I think having a doc.nuttx.org site or something similar to Zephyr's would really increase the user-friendliness of NuttX. That said, I can help in both efforts, this is something I've been meaning to work on for sometime and there was simply no infrastructure available at the moment (that is why I worked on the NuttX GitBook but such effort is definitely not for just one person). Best, Matias On Thu, Jul 16, 2020, at 01:20, Adam Feuer wrote: > Zephyr uses Sphinx <https://www.sphinx-doc.org/en/master/> and ReStructured > Text (RST) <https://docutils.sourceforge.io/rst.html>for their docs. I'm a > fan obviously, it's great for writing hyperlinked technical documentation. > Sphinx requires Python, though. > > The board list with pictures is a great idea, and I'd be willing to help > with it. > > -adam > > On Wed, Jul 15, 2020 at 9:11 PM Maciej Wójcik <w8j...@gmail.com> wrote: > > > > what do you think about using Markdown for README files? > > > > Since the project was very conservative so far, I used regular expression > > to parse some existing files into Markdown. Although it is not completely > > reliable. I also think that markdown in repository would be great. > > > > Even trying to sneak in some first Markdown file already :D > > > > https://github.com/apache/incubator-nuttx-apps/blob/2fdd7529251919315bce62ceb0b130d7f135c506/graphics/lvgl/README.md > > > > > One of the reasons I really like the Zephyr docs... > > > > Yes, it is also my impression. This is why I am trying to create > > interactive documentation right now. > > > > Kconfig NuttX data is extracted using the same library as Zephyr does. > > > > Here are some existing READMES parsed into markdown > > http://nuttx-config.nxtlabs.pl/#/apps. To be more specific > > apps/*/README.txt files. > > > > I would like to add boards section as well in form of tiles with pictures > > and board configuration support comparison inspired by this > > https://node.green. > > > > Complete tree of READMEs with a search is also in my mind > > https://gitlab.com/nuttx-upm/kconfig-browser/web-ui/-/issues/25 > > > > How it works: currently there is a pipeline which runs for multiple > > tags/branches (master, releases/9.1, releases/9.0, ...) and extracts data > > into static JSON. Then Vue.js application is trying to render it. Pipeline > > triggers automatically weekly to keep the master fresh. > > > > > > Am Do., 16. Juli 2020 um 03:55 Uhr schrieb Matias N. <mat...@imap.cc>: > > > > > On Wed, Jul 15, 2020, at 22:45, Brennan Ashton wrote: > > > > I would be huge fan of this. It makes it a lot more approachable, I > > had > > > > started converting the main readme in particular but I did not get very > > > > far. It's a lot of work. > > > > > > I can help with that if you want > > > > > > > Did you see Adams work here > > > > https://nuttx-companion.readthedocs.io/en/latest/ > > > > > > > > I thought it would be really nice to integrate the board list with the > > > > readme content into it. (While keeping the content readable in the > > source > > > > control). > > > > > > Yes, I was actually imagining some sort of CI command on the website (not > > > sure the wiki handles that) that could build a list with all boards > > > containing a README, link to it and display it there nicely formatted. > > > Something like readthedocs could possibly do it already, not sure. > > > > > > One of the reasons I really like the Zephyr docs is because of this, you > > > can see how they present their supported boards there: > > > https://docs.zephyrproject.org/latest/boards/index.html > > > Even further, each board description has a nice picture, specification > > > list, etc. I thank that would be really useful and easy to do (the > > picture > > > could be stored in some stable location and the README simply link to > > it). > > > > > > Best, > > > Matias > > > > > -- > Adam Feuer <a...@starcat.io> >
