Please make sure the readmes are still easily readable in vim and other
plain text editors.
Plain text is good.
underlined plain text interpreted by github is still readable (markdown?)
anything that requires writing explicit tag in the readme text files
should be avoided imho.
also, anything that requires non-trivial tools for reading is to be
excluded.
asciidoctor requires ruby
Not sure that throwing more tools in the mix is even useful...
Sebastien
Le 16/07/2020 à 17:56, Adam Feuer a écrit :
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>
