Re: Markdown READMEs?

[Justin Mclean]

Hi,

You might want to look at https://asciidoctor.org It an improved markdown with 
a few more features and multiple outputs.

Thanks,
Justin

Re: Markdown READMEs?

[Adam Feuer]

Zephyr uses Sphinx  and ReStructured
Text (RST) 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  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. :
>
> > 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 

Re: Markdown READMEs?

[Maciej Wójcik]

> 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. :

> 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

Re: Markdown READMEs?

[Matias N.]

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

Re: Markdown READMEs?

[Brennan Ashton]

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.

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).

You already seeing the Linux kernel making some progress in this direction
(not quite markdown)
https://www.kernel.org/doc/html/v4.10/index.html

We are already using some markup of sorts so I don't see why this would be
a problem, but that's just my one opinion.

--Brennan

On Wed, Jul 15, 2020, 6:27 PM Matias N.  wrote:

> Hi,
> what do you think about using Markdown for README files? I think the
> syntax is good for direct reading but it also has the added benefit of
> being supported with nice rendering in different platforms, such as GitHub
> itself. Maybe this can also be used to expose the READMEs in the
> wiki/website which I understand are also in Markdown.
>
> Best,
> Matias

Markdown READMEs?

[Matias N.]

Hi,
what do you think about using Markdown for README files? I think the syntax is 
good for direct reading but it also has the added benefit of being supported 
with nice rendering in different platforms, such as GitHub itself. Maybe this 
can also be used to expose the READMEs in the wiki/website which I understand 
are also in Markdown.

Best,
Matias

[nuttx][avr] Issues while building avr (atmega) board example.

[Pavel Ionut]

Hello,

Basically I'm trying to build the moteino-mega board example and I found
some issues.
I have prepared a fix for all of these issues, but first of all I want your
opinion on one of the issues.

Seems like the linux avr-gcc does not include double_t as a type inside the
compiler provided , and double_t is used inside the libs and the
build fails.

One possible fix (currently using) is to typedef it inside compiler.h (for
the AVR compiler), however, I don't know if this would be correct since I
see no other typedefs inside that file.

Regards