I like the idea of doing a ReStructured Text build in CI. I'd help convert READMEs and other docs to RST. And I'd be willing to contribute the RST docs I have already as a starting place if people are interested. They are already Apache 2.0 Licensed.
-adam On Thu, Jul 16, 2020 at 6:45 AM Matias N. <mat...@imap.cc> wrote: > 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> > > > -- Adam Feuer <a...@starcat.io>
