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>
