Re: Markdown READMEs?

[Maciej Wójcik]

This PR changes all READMEs in `apps` repository into Markdown

https://github.com/apache/incubator-nuttx-apps/pull/337

More in the description.

Am Di., 21. Juli 2020 um 20:37 Uhr schrieb Adam Feuer :

> Matias,
>
> Yes, I have the NuttX.html file partially converted. I'll see if I can get
> that a little close today and submit a PR to your branch.
>
> -adam
>
> On Tue, Jul 21, 2020 at 11:23 AM Matias N.  wrote:
>
> > Ok, got it sooner than expected. The docs are published to:
> > https://v01d.github.io/incubator-nuttx/ <
> > https://v01d.github.io/incubator-nuttx/docs/index.html>
> > Right now as we're working on a "docs" branch in this fork, you can see
> it
> > generated here:
> > https://v01d.github.io/incubator-nuttx/docs/index.html
> > On pull-requests it only does the build and not the publish (not tested
> > this yet). Would be cool to have PRs viewable somewhere but that is more
> > complex.
> >
> > Now we could work a bit on the content. I would iterate on a proposed
> > structure and put some placeholders.
> > Adam, you mentioned you wanted to convert on HTML file for demonstration
> > purposes. Do you want to do that?
> >
> > Best,
> > Matias
> >
> > On Tue, Jul 21, 2020, at 15:11, Matias N. wrote:
> > > Hi,
> > > yes, we have CI building sphinx already. I'm now trying to get this be
> > published via GitHub pages using a subdirectory per version (version
> would
> > be "master" or the tip of each release or the tag name). Anyways, this is
> > not how it would work exactly in the end since the website repo would
> take
> > care of this. But probably some components of the CI system would be
> > similar. Also, this allows to have something to show when by put a bit of
> > content there for demonstration purposes.
> > >
> > > Will let you know when I get something to show.
> > >
> > > Best,
> > > Matias
> > >
> > > On Tue, Jul 21, 2020, at 15:02, Adam Feuer wrote:
> > >> Brennan,
> > >>
> > >> Cool, that's awesome. I didn't know that discussion was going on in
> the
> > PR.
> > >> :)
> > >>
> > >> -adam
> > >>
> > >> On Tue, Jul 21, 2020 at 10:55 AM Brennan Ashton <
> > bash...@brennanashton.com>
> > >> wrote:
> > >>
> > >> > On Tue, Jul 21, 2020, 10:51 AM Adam Feuer  wrote:
> > >> >
> > >> > > Matias, Maciej,
> > >> > >
> > >> > > Ok, I looked into doing a Sphinx build of RST and Markdown via
> > Github and
> > >> > > publishing to Github pages automatically. People have done it, but
> > it's a
> > >> > > bit more complicated than I thought. I'll see if I can get it
> > worked out
> > >> > in
> > >> > > my repo first and then we can go from there. It will take me a few
> > days
> > >> > > because I have other stuff going on too.
> > >> > >
> > >> > > -adam
> > >> > >
> > >> >
> > >> > Hey Adam yesterday I submitted the PR for doing the build via GitHub
> > >> > Actions and it generates the artifacts.  I would not worry too much
> > about
> > >> > GitHub pages since we need to get it attached to the Apache system.
> > >> >
> > >> > You can see some of the discussion here
> > >> >
> https://github.com/v01d/incubator-nuttx/pull/1#issuecomment-661952429
> > >> >
> > >> > --Brennan
> > >> >
> > >>
> > >>
> > >> --
> > >> Adam Feuer 
> > >>
> > >
> >
>
>
> --
> Adam Feuer 
>

Re: Markdown READMEs?

[Adam Feuer]

Matias,

Yes, I have the NuttX.html file partially converted. I'll see if I can get
that a little close today and submit a PR to your branch.

-adam

On Tue, Jul 21, 2020 at 11:23 AM Matias N.  wrote:

> Ok, got it sooner than expected. The docs are published to:
> https://v01d.github.io/incubator-nuttx/ <
> https://v01d.github.io/incubator-nuttx/docs/index.html>
> Right now as we're working on a "docs" branch in this fork, you can see it
> generated here:
> https://v01d.github.io/incubator-nuttx/docs/index.html
> On pull-requests it only does the build and not the publish (not tested
> this yet). Would be cool to have PRs viewable somewhere but that is more
> complex.
>
> Now we could work a bit on the content. I would iterate on a proposed
> structure and put some placeholders.
> Adam, you mentioned you wanted to convert on HTML file for demonstration
> purposes. Do you want to do that?
>
> Best,
> Matias
>
> On Tue, Jul 21, 2020, at 15:11, Matias N. wrote:
> > Hi,
> > yes, we have CI building sphinx already. I'm now trying to get this be
> published via GitHub pages using a subdirectory per version (version would
> be "master" or the tip of each release or the tag name). Anyways, this is
> not how it would work exactly in the end since the website repo would take
> care of this. But probably some components of the CI system would be
> similar. Also, this allows to have something to show when by put a bit of
> content there for demonstration purposes.
> >
> > Will let you know when I get something to show.
> >
> > Best,
> > Matias
> >
> > On Tue, Jul 21, 2020, at 15:02, Adam Feuer wrote:
> >> Brennan,
> >>
> >> Cool, that's awesome. I didn't know that discussion was going on in the
> PR.
> >> :)
> >>
> >> -adam
> >>
> >> On Tue, Jul 21, 2020 at 10:55 AM Brennan Ashton <
> bash...@brennanashton.com>
> >> wrote:
> >>
> >> > On Tue, Jul 21, 2020, 10:51 AM Adam Feuer  wrote:
> >> >
> >> > > Matias, Maciej,
> >> > >
> >> > > Ok, I looked into doing a Sphinx build of RST and Markdown via
> Github and
> >> > > publishing to Github pages automatically. People have done it, but
> it's a
> >> > > bit more complicated than I thought. I'll see if I can get it
> worked out
> >> > in
> >> > > my repo first and then we can go from there. It will take me a few
> days
> >> > > because I have other stuff going on too.
> >> > >
> >> > > -adam
> >> > >
> >> >
> >> > Hey Adam yesterday I submitted the PR for doing the build via GitHub
> >> > Actions and it generates the artifacts.  I would not worry too much
> about
> >> > GitHub pages since we need to get it attached to the Apache system.
> >> >
> >> > You can see some of the discussion here
> >> > https://github.com/v01d/incubator-nuttx/pull/1#issuecomment-661952429
> >> >
> >> > --Brennan
> >> >
> >>
> >>
> >> --
> >> Adam Feuer 
> >>
> >
>


-- 
Adam Feuer 

Re: Markdown READMEs?

[Matias N.]

Ok, got it sooner than expected. The docs are published to: 
https://v01d.github.io/incubator-nuttx/ 

Right now as we're working on a "docs" branch in this fork, you can see it 
generated here:
https://v01d.github.io/incubator-nuttx/docs/index.html
On pull-requests it only does the build and not the publish (not tested this 
yet). Would be cool to have PRs viewable somewhere but that is more complex.

Now we could work a bit on the content. I would iterate on a proposed structure 
and put some placeholders.
Adam, you mentioned you wanted to convert on HTML file for demonstration 
purposes. Do you want to do that?

Best,
Matias

On Tue, Jul 21, 2020, at 15:11, Matias N. wrote:
> Hi,
> yes, we have CI building sphinx already. I'm now trying to get this be 
> published via GitHub pages using a subdirectory per version (version would be 
> "master" or the tip of each release or the tag name). Anyways, this is not 
> how it would work exactly in the end since the website repo would take care 
> of this. But probably some components of the CI system would be similar. 
> Also, this allows to have something to show when by put a bit of content 
> there for demonstration purposes.
> 
> Will let you know when I get something to show.
> 
> Best,
> Matias
> 
> On Tue, Jul 21, 2020, at 15:02, Adam Feuer wrote:
>> Brennan,
>> 
>> Cool, that's awesome. I didn't know that discussion was going on in the PR.
>> :)
>> 
>> -adam
>> 
>> On Tue, Jul 21, 2020 at 10:55 AM Brennan Ashton 
>> wrote:
>> 
>> > On Tue, Jul 21, 2020, 10:51 AM Adam Feuer  wrote:
>> >
>> > > Matias, Maciej,
>> > >
>> > > Ok, I looked into doing a Sphinx build of RST and Markdown via Github and
>> > > publishing to Github pages automatically. People have done it, but it's a
>> > > bit more complicated than I thought. I'll see if I can get it worked out
>> > in
>> > > my repo first and then we can go from there. It will take me a few days
>> > > because I have other stuff going on too.
>> > >
>> > > -adam
>> > >
>> >
>> > Hey Adam yesterday I submitted the PR for doing the build via GitHub
>> > Actions and it generates the artifacts.  I would not worry too much about
>> > GitHub pages since we need to get it attached to the Apache system.
>> >
>> > You can see some of the discussion here
>> > https://github.com/v01d/incubator-nuttx/pull/1#issuecomment-661952429
>> >
>> > --Brennan
>> >
>> 
>> 
>> -- 
>> Adam Feuer 
>> 
> 

Re: Markdown READMEs?

[Matias N.]

Hi,
yes, we have CI building sphinx already. I'm now trying to get this be 
published via GitHub pages using a subdirectory per version (version would be 
"master" or the tip of each release or the tag name). Anyways, this is not how 
it would work exactly in the end since the website repo would take care of 
this. But probably some components of the CI system would be similar. Also, 
this allows to have something to show when by put a bit of content there for 
demonstration purposes.

Will let you know when I get something to show.

Best,
Matias

On Tue, Jul 21, 2020, at 15:02, Adam Feuer wrote:
> Brennan,
> 
> Cool, that's awesome. I didn't know that discussion was going on in the PR.
> :)
> 
> -adam
> 
> On Tue, Jul 21, 2020 at 10:55 AM Brennan Ashton 
> wrote:
> 
> > On Tue, Jul 21, 2020, 10:51 AM Adam Feuer  wrote:
> >
> > > Matias, Maciej,
> > >
> > > Ok, I looked into doing a Sphinx build of RST and Markdown via Github and
> > > publishing to Github pages automatically. People have done it, but it's a
> > > bit more complicated than I thought. I'll see if I can get it worked out
> > in
> > > my repo first and then we can go from there. It will take me a few days
> > > because I have other stuff going on too.
> > >
> > > -adam
> > >
> >
> > Hey Adam yesterday I submitted the PR for doing the build via GitHub
> > Actions and it generates the artifacts.  I would not worry too much about
> > GitHub pages since we need to get it attached to the Apache system.
> >
> > You can see some of the discussion here
> > https://github.com/v01d/incubator-nuttx/pull/1#issuecomment-661952429
> >
> > --Brennan
> >
> 
> 
> -- 
> Adam Feuer 
> 

Re: Markdown READMEs?

[Brennan Ashton]

On Tue, Jul 21, 2020, 10:51 AM Adam Feuer  wrote:

> Matias, Maciej,
>
> Ok, I looked into doing a Sphinx build of RST and Markdown via Github and
> publishing to Github pages automatically. People have done it, but it's a
> bit more complicated than I thought. I'll see if I can get it worked out in
> my repo first and then we can go from there. It will take me a few days
> because I have other stuff going on too.
>
> -adam
>

Hey Adam yesterday I submitted the PR for doing the build via GitHub
Actions and it generates the artifacts.  I would not worry too much about
GitHub pages since we need to get it attached to the Apache system.

You can see some of the discussion here
https://github.com/v01d/incubator-nuttx/pull/1#issuecomment-661952429

--Brennan

RE: Markdown READMEs?

[Xiang Xiao]

I found several problem with Confluence:
1.It's impossible to update document in batch
2.People without apache account can't modify the document
3.It's hard to add review process before applying the change
4.Newbie can't easily find all documents
If we move all documents to https://github.com/apache/incubator-nuttx, all 
issues get fixed automatically.

> -Original Message-
> From: Gregory Nutt 
> Sent: Tuesday, July 21, 2020 7:08 AM
> To: dev@nuttx.apache.org
> Subject: Re: Markdown READMEs?
> 
> For those really opposed to HTML, another option is to simply use the 
> Confluence versions of the documents here:
> https://cwiki.apache.org/confluence/display/NUTTX/Documentation
> 
> These are the same documents that are currently in nuttx/Documentation. They 
> are read-only now (since the master is in the
> repository), but imagine that could change.
> 

Re: Markdown READMEs?

[spudaneco]

Versioning is important but I think that the most important reason to keep the 
docs in the repositories is because we have a visible, manageable process to 
update critical documents via PRs.  For example,changes to the coding standard 
need careful review and approval.Sent from Samsung tablet.
null

Re: Markdown READMEs?

[Adam Feuer]

On Mon, Jul 20, 2020 at 4:32 PM Justin Mclean 
wrote:

> That's a great idea, but it may have some impact on teh LICENSE file
> depending on what libraries, fonts etc are bundled with the documentation.
> You may need to make sure that nothing with an incomparable license sneaks
> in.
>

The current docs are pure HTML and text, so I don't think there are any
fonts in there.

-adam
-- 
Adam Feuer 

Re: Markdown READMEs?

[Justin Mclean]

Hi,

> I also love having the docs in the repository and releases, and versioned
> along with the code. It makes things so much easier.

That's a great idea, but it may have some impact on teh LICENSE file depending 
on what libraries, fonts etc are bundled with the documentation. You may need 
to make sure that nothing with an incomparable license sneaks in.

Thanks,
Justin

Re: Markdown READMEs?

[Adam Feuer]

I also love having the docs in the repository and releases, and versioned
along with the code. It makes things so much easier.

If I had to pick between the current docs (HTML/txt) and the wiki, I would
pick the current docs!

-adam

On Mon, Jul 20, 2020 at 4:17 PM Nathan Hartman 
wrote:

> On Mon, Jul 20, 2020 at 7:07 PM Gregory Nutt  wrote:
>
> > For those really opposed to HTML, another option is to simply use the
> > Confluence versions of the documents here:
> > https://cwiki.apache.org/confluence/display/NUTTX/Documentation
> >
> > These are the same documents that are currently in nuttx/Documentation.
> > They are read-only now (since the master is in the repository), but
> > imagine that could change.
>
>
> I think there is an advantage to documentation being in the repository (and
> by extension in the releases): Longevity of the documents. If someone has a
> copy of the tarball and no Internet, they have the docs. I suppose this
> might be less of a concern today than it was in the past, but I think
> there's some legitimacy to it still.
>
> Nathan
>


-- 
Adam Feuer 

Re: Markdown READMEs?

[Nathan Hartman]

On Mon, Jul 20, 2020 at 7:07 PM Gregory Nutt  wrote:

> For those really opposed to HTML, another option is to simply use the
> Confluence versions of the documents here:
> https://cwiki.apache.org/confluence/display/NUTTX/Documentation
>
> These are the same documents that are currently in nuttx/Documentation.
> They are read-only now (since the master is in the repository), but
> imagine that could change.


I think there is an advantage to documentation being in the repository (and
by extension in the releases): Longevity of the documents. If someone has a
copy of the tarball and no Internet, they have the docs. I suppose this
might be less of a concern today than it was in the past, but I think
there's some legitimacy to it still.

Nathan

Re: Markdown READMEs?

[Gregory Nutt]

For those really opposed to HTML, another option is to simply use the 
Confluence versions of the documents here: 
https://cwiki.apache.org/confluence/display/NUTTX/Documentation


These are the same documents that are currently in nuttx/Documentation.  
They are read-only now (since the master is in the repository), but 
imagine that could change.

Re: Markdown READMEs?

[Gregory Nutt]

I will do a PR to your branch and repo, but will you create a branch 
and put your changes on it? The branch should be called something like 
feature/sphinx-docs.


If you do that, I can do PR directly to that branch. Having it on a 
branch other than master will make it easier to submit later, if 
people want it to go into the main incubator-nuttx repo.


Re: should we do work on it without a vote? I don't know, I'm not a 
PPMC member either and don't know the process. Since we're discussing 
here on the list in public, I am hoping that if we're going the wrong 
direction, someone will say something to guide us the right way. I 
think doing some work on a public branch that gets rendered to Read 
The Docs would help right now, so people can see the source code and 
the rendered docs and make a decision based on that. Taking a vote 
without having some sample docs to look at doesn't seem optimal.


My inclination would be to get one HTML page completed, one regular 
README, and one or two board READMEs done and working– that will give 
people a better idea if this is going in the right direction.
I hope that people understand that after you modify the HTML 
documentation, you own it.  I will no longer be maintaining the 
documentation.

Re: Markdown READMEs?

[Gregory Nutt]

Hi guys. In the meantime, I carefully converted most of the readmes in 
the `apps` repository. Four folders left


- [x] main readme
- [x] netutils
- [x] wireless
- [x] examples
- [x] modbus
- [x] fsutils
- [x] gpsutils
- [ ] testing
- [ ] system
- [x] tools
- [x] industry
- [x] interpreters
- [ ] graphics
- [ ] nshlib


The main repository is the challenge:

$ find . -name "README*" | wc -l
273

Re: Markdown READMEs?

[Matias N.]

> Sure. I created a "docs" branch on https://github.com/v01d/incubator-nuttx/ 
> I'm mostly experimenting right now anyways. Should we wait for an official 
> vote to confirm we're heading
> in the right direction? Migrating documentation also will require some 
> coordination to avoid introducing
> big changes to HTMLs or wiki during migration.

PS: it would be cool if you could make a PR to this repo including the required 
GitHub files to make sphinx build to GitHub pages. This way it would be easier 
to test the ongoing work.

Re: Markdown READMEs?

[Adam Feuer]

Thanks Matias.

Following Matias' proposal, here's a separate repo with just one page of
the HTML docs partially converted:

https://github.com/adamfeuer/nuttx-docs

The files here could also be copied into a directory in the nuttx source
tree too, for instance under Documentation/sphinx-docs instead of living in
a separate repo.

You can see the docs rendered using the Sphinx Read the Docs Theme here:

https://nuttx-docs.readthedocs.io

I converted this with pandoc and some Vim macros– the supported boards
table didn't get done right, so needs more work, and pandoc also messed up
the internal links, so they need to be fixed. But this gives the idea about
how the docs would look, at least.

I'll add an example Markdown file here so we can look at how the mixed
ReStructuredText / Markdown stuff looks together.

-adam

On Mon, Jul 20, 2020 at 2:26 AM Xiang Xiao 
wrote:

> Can we keep the doc and nuttx in one git? The major of document is
> normally couple with the code. The separation make the
> synchronization between code and document more harder. Other similar
> project(e.g. Linux and Zephyr) use the same git manage both
> code and document:
> https://github.com/torvalds/linux/tree/master/Documentation
> https://github.com/zephyrproject-rtos/zephyr/tree/master/doc
> Other propose looks good to me. Maybe we can integrate wiki into the new
> document structure later.
>
> Thanks
> Xiang
>
> > -Original Message-
> > From: Matias N. 
> > Sent: Monday, July 20, 2020 11:39 AM
> > To: dev@nuttx.apache.org
> > Subject: Re: Markdown READMEs?
> >
> > Hi,
> > after reading all responses I would propose to:
> >
> > 1. use Markdown for all READMEs: the syntax is simple and perfectly
> readable in pure text
> >
> > 2. start a doc-specific repo using RST format (has nice support for
> writing API descriptions, among other things useful for
> technical docs)
> > which would generate the documentation using Sphinx on GitHub CI and
> make that available somewhere in the website. Using
> > GitHub CI to build docs using Sphinx appears also very easy:
> https://github.com/marketplace/actions/sphinx-build. The
> "readthedocs"
> > theme looks very nice also:
> https://sphinx-rtd-theme.readthedocs.io/en/stable/
> >
> > For (1) I can start by porting the main README and maybe then we could
> distribute the task for all other READMEs.
> > Regarding (2), this repository would follow versioning of NuttX as well
> as mater. On the website one can choose which version of
> the
> > documentation to display.
> >
> > Best,
> > Matias
>
>

-- 
Adam Feuer 

Re: Markdown READMEs?

[Bill Rees]

+1
Maintaining code coherency (including docs) is YUUGely more difficult 
when separate repos are involved.


If the main reason for creating a second repo is to more cleanly have 
two doc directories maybe Markdown isn't the answer you want anyway.


If the focus on pretty print is to use RST then "compile" READMEs from 
the RST forms. Markdown doesn't really add much to a doc, IMHO, so 
generating a README.txt  from a RST based source would seem to be optimal.


Hell, Github may even take a PR for that feature.

Thanks,
Bill

On 7/20/2020 2:26 AM, Xiang Xiao wrote:

Can we keep the doc and nuttx in one git? The major of document is normally 
couple with the code. The separation make the
synchronization between code and document more harder. Other similar 
project(e.g. Linux and Zephyr) use the same git manage both
code and document:
https://github.com/torvalds/linux/tree/master/Documentation
https://github.com/zephyrproject-rtos/zephyr/tree/master/doc
Other propose looks good to me. Maybe we can integrate wiki into the new 
document structure later.

Thanks
Xiang


-Original Message-
From: Matias N. 
Sent: Monday, July 20, 2020 11:39 AM
To: dev@nuttx.apache.org
Subject: Re: Markdown READMEs?

Hi,
after reading all responses I would propose to:

1. use Markdown for all READMEs: the syntax is simple and perfectly readable in 
pure text

2. start a doc-specific repo using RST format (has nice support for writing API 
descriptions, among other things useful for

technical docs)

which would generate the documentation using Sphinx on GitHub CI and make that 
available somewhere in the website. Using
GitHub CI to build docs using Sphinx appears also very easy: 
https://github.com/marketplace/actions/sphinx-build. The

"readthedocs"

theme looks very nice also: https://sphinx-rtd-theme.readthedocs.io/en/stable/

For (1) I can start by porting the main README and maybe then we could 
distribute the task for all other READMEs.
Regarding (2), this repository would follow versioning of NuttX as well as 
mater. On the website one can choose which version of

the

documentation to display.

Best,
Matias

RE: Markdown READMEs?

[Xiang Xiao]

Can we keep the doc and nuttx in one git? The major of document is normally 
couple with the code. The separation make the
synchronization between code and document more harder. Other similar 
project(e.g. Linux and Zephyr) use the same git manage both
code and document:
https://github.com/torvalds/linux/tree/master/Documentation
https://github.com/zephyrproject-rtos/zephyr/tree/master/doc 
Other propose looks good to me. Maybe we can integrate wiki into the new 
document structure later.

Thanks
Xiang

> -Original Message-
> From: Matias N. 
> Sent: Monday, July 20, 2020 11:39 AM
> To: dev@nuttx.apache.org
> Subject: Re: Markdown READMEs?
> 
> Hi,
> after reading all responses I would propose to:
> 
> 1. use Markdown for all READMEs: the syntax is simple and perfectly readable 
> in pure text
> 
> 2. start a doc-specific repo using RST format (has nice support for writing 
> API descriptions, among other things useful for
technical docs)
> which would generate the documentation using Sphinx on GitHub CI and make 
> that available somewhere in the website. Using
> GitHub CI to build docs using Sphinx appears also very easy: 
> https://github.com/marketplace/actions/sphinx-build. The
"readthedocs"
> theme looks very nice also: https://sphinx-rtd-theme.readthedocs.io/en/stable/
> 
> For (1) I can start by porting the main README and maybe then we could 
> distribute the task for all other READMEs.
> Regarding (2), this repository would follow versioning of NuttX as well as 
> mater. On the website one can choose which version of
the
> documentation to display.
> 
> Best,
> Matias

Re: Markdown READMEs?

[Brennan Ashton]

On Sun, Jul 19, 2020 at 9:27 PM Matias N.  wrote:
>
> > An example readme conversion might also
> > be helpful to outline what this looks like for people who are
> > concerned about it remaining plaintext (I agree that it is)
>
> That was also a reason why I proposed starting with just the main README, 
> which I think is the most "complex" README on the repo. I can open a PR for 
> that.

That sounds great! Thanks for doing this work.

--Brennan

Re: Markdown READMEs?

[Matias N.]

On Mon, Jul 20, 2020, at 00:59, Brennan Ashton wrote:
> Matias,
> I think this sounds reasonable and I am happy to help.  I'm a little
> conflicted about having two different markdown formats one for readmes
> and one for true documentation, but we already have that to some
> extent with the html docs, and sphinx can bridge the gap a little
> anyway allowing embedding of markdown in its pages.

I proposed separate formats because I believe RST has the advantages I 
mentioned, however as other members expressed concerns about readability of 
README files, I think Markdown is more suitable since it does not require any 
"tag" to achieve most of its formatting.

> The one thing I would ask because this is a large undertaking and has
> a large impact on the project is that you call an actual vote on it to
> make sure we have agreement.

As I'm not an official maintainer I was unsure if calling a vote myself was 
appropriate.
For that reason my last email was mostly to not loose track of this discussion 
and summarize to
what I understood was discussed so far.

> An example readme conversion might also
> be helpful to outline what this looks like for people who are
> concerned about it remaining plaintext (I agree that it is)

That was also a reason why I proposed starting with just the main README, which 
I think is the most "complex" README on the repo. I can open a PR for that.

Best,
Matias

> 
> --Brennan
> 
> On Sun, Jul 19, 2020 at 8:40 PM Matias N.  wrote:
> >
> > Hi,
> > after reading all responses I would propose to:
> >
> > 1. use Markdown for all READMEs: the syntax is simple and perfectly 
> > readable in pure text
> >
> > 2. start a doc-specific repo using RST format (has nice support for writing 
> > API descriptions, among other things useful for technical docs) which would 
> > generate the documentation using Sphinx on GitHub CI and make that 
> > available somewhere in the website. Using GitHub CI to build docs using 
> > Sphinx appears also very easy: 
> > https://github.com/marketplace/actions/sphinx-build. The "readthedocs" 
> > theme looks very nice also: 
> > https://sphinx-rtd-theme.readthedocs.io/en/stable/
> >
> > For (1) I can start by porting the main README and maybe then we could 
> > distribute the task for all other READMEs.
> > Regarding (2), this repository would follow versioning of NuttX as well as 
> > mater. On the website one can choose which version of the documentation to 
> > display.
> >
> > Best,
> > Matias
> 

Re: Markdown READMEs?

[Brennan Ashton]

Matias,
I think this sounds reasonable and I am happy to help.  I'm a little
conflicted about having two different markdown formats one for readmes
and one for true documentation, but we already have that to some
extent with the html docs, and sphinx can bridge the gap a little
anyway allowing embedding of markdown in its pages.

The one thing I would ask because this is a large undertaking and has
a large impact on the project is that you call an actual vote on it to
make sure we have agreement.  An example readme conversion might also
be helpful to outline what this looks like for people who are
concerned about it remaining plaintext (I agree that it is)

--Brennan

On Sun, Jul 19, 2020 at 8:40 PM Matias N.  wrote:
>
> Hi,
> after reading all responses I would propose to:
>
> 1. use Markdown for all READMEs: the syntax is simple and perfectly readable 
> in pure text
>
> 2. start a doc-specific repo using RST format (has nice support for writing 
> API descriptions, among other things useful for technical docs) which would 
> generate the documentation using Sphinx on GitHub CI and make that available 
> somewhere in the website. Using GitHub CI to build docs using Sphinx appears 
> also very easy: https://github.com/marketplace/actions/sphinx-build. The 
> "readthedocs" theme looks very nice also: 
> https://sphinx-rtd-theme.readthedocs.io/en/stable/
>
> For (1) I can start by porting the main README and maybe then we could 
> distribute the task for all other READMEs.
> Regarding (2), this repository would follow versioning of NuttX as well as 
> mater. On the website one can choose which version of the documentation to 
> display.
>
> Best,
> Matias

Re: Markdown READMEs?

[Matias N.]

Hi,
after reading all responses I would propose to:

1. use Markdown for all READMEs: the syntax is simple and perfectly readable in 
pure text

2. start a doc-specific repo using RST format (has nice support for writing API 
descriptions, among other things useful for technical docs) which would 
generate the documentation using Sphinx on GitHub CI and make that available 
somewhere in the website. Using GitHub CI to build docs using Sphinx appears 
also very easy: https://github.com/marketplace/actions/sphinx-build. The 
"readthedocs" theme looks very nice also: 
https://sphinx-rtd-theme.readthedocs.io/en/stable/

For (1) I can start by porting the main README and maybe then we could 
distribute the task for all other READMEs. 
Regarding (2), this repository would follow versioning of NuttX as well as 
mater. On the website one can choose which version of the documentation to 
display.

Best,
Matias

Re: Markdown READMEs?

[Justin Mclean]

Hi,

> asciidoctor requires ruby

You can use it that way yes but it not required.

One other ways of doing so including javascript for displaying markdown content 
on a website.

Justin

Re: Markdown READMEs?

[Adam Feuer]

Version documentation is quite useful, specially for such a dynamic project
> as NuttX. I'm not sure it would require to have everything in a single
> repo, since it is not really necessary to tie every single code commit to a
> doc commit. I think a doc for master, updated as the code evolves, while
> having doc tagged with the same version numbers as the codebase, could be
> already enough and simple enough.


That works– what I was trying to say was that the docs need to have the
same version as the release numbers, so you can know you're reading
accurate docs for that version. As long as we have process to keep them in
sync, we're good.

Having separate repos will also simplify dealing with doc PRs vs code PRs,
> can have different maintainers, requirements, CI system, etc. (imagine
> having a doc update triggering a full CI rebuild).
>

To me, it's a preference– with most CI systems you can set it to watch
certain directories or types of files.

Again, I would encourage you to think in a scenario where you have a
> specific repo holding all documentation which describes how to use and work
> with NuttX, starting from simple "quickstart", to advanced technical
> information and even an API reference.


Agreed. This is also my vision.


> In that case, READMEs throughout the repo would not need to have a lot of
> the information that today exists there, sprinkled in all of the READMEs.
> For that reason, I don't think it is worth it using something richer than
> Markdown for READMEs.
>

As long as we can mix Markdown and RST (or whatever we use for the richer
documentation) then Markdown is ok with me. Where this would come in handy
is something like the Supported Boards tree you've been describing. In
Zephyr each board doc is a seamless part of the main docs.


> Anyways, if it comes down to "use the same for everything, or leave it as
> is" I would indeed vote for the first option


Likewise. But if we use Sphinx we can mix Markdown and RST. However, Zephyr
went with "everything the same"  and just uses RST (Zephyr supported boards
; example board
Nitrogen
;
example board nitrogen RST on github

).

-adam
-- 
Adam Feuer 

Re: Markdown READMEs?

[Matias N.]

On Fri, Jul 17, 2020, at 13:39, Adam Feuer wrote:
> A few comments:
> 
>- It would be great to have the documentation in the same repository, to
>make synchronizing a particular documentation version with the code.
>- Or if we don't do that, have some other explicit versioning that
>   matches the code, and do simultaneous releases. Code and docs
> synchronized
>   will make peoples' lives a lot easier.

Version documentation is quite useful, specially for such a dynamic project as 
NuttX. I'm not sure it would require to have everything in a single repo, since 
it is not really necessary to tie every single code commit to a doc commit. I 
think a doc for master, updated as the code evolves, while having doc tagged 
with the same version numbers as the codebase, could be already enough and 
simple enough. Having separate repos will also simplify dealing with doc PRs vs 
code PRs, can have different maintainers, requirements, CI system, etc. 
(imagine having a doc update triggering a full CI rebuild).

>- RST is as readable in plain text format as Markdown, and is also
>rendered automatically by Github (example rendered by Github
>
> ;
>raw version
>
> 
>).
>- The main difference between RST and Markdown formatting is the way
>links are handled. RST has a different link format and also has support for
>internal linking– in my opinion that's what makes RST really good for
>technical documentation.
>- Converting READMEs to RST or Markdown can be done manually or
>semi-manually, it's not that hard. We could design a system that included
>both text and RST or Markdown to support the transition.
>- Sphinx supports generating documentation using both RST and Markdown
>(recommonmark) so
>you can mix them.
> 
> I think getting our docs and READMEs into a single system using RST or
> RST/Markdown would be great.

IMHO, each format has its benefits: 
- Markdown, simple, very readable
- Rest: richer syntax, not that nice to read as Markdown

Again, I would encourage you to think in a scenario where you have a specific 
repo holding all documentation which describes how to use and work with NuttX, 
starting from simple "quickstart", to advanced technical information and even 
an API reference. In that case, READMEs throughout the repo would not need to 
have a lot of the information that today exists there, sprinkled in all of the 
READMEs. For that reason, I don't think it is worth it using something richer 
than Markdown for READMEs. 
Anyways, if it comes down to "use the same for everything, or leave it as is" I 
would indeed vote for the first option.

Best,
Matias

> 
> -adam
> 
> On Fri, Jul 17, 2020 at 9:23 AM Abdelatif Guettouche <
> abdelatif.guettou...@gmail.com> wrote:
> 
> > It would be great to have READMEs in Markdown, as said before, it's
> > still plain text and can be rendered by other tools/websites.  Because
> > it was brought out, VIM also has plugins for syntax highlighting,
> > instant rendering, etc.
> > It was also suggested to use Markdown for release notes.
> >
> > On Fri, Jul 17, 2020 at 5:12 PM Matias N.  wrote:
> > >
> > > No problem, just wanted to clear any possible confusion when considering
> > the idea.
> > >
> > > On Fri, Jul 17, 2020, at 13:09, Maciej Wójcik wrote:
> > > > Sure, Matias. I was not addressing your proposition in any way. I was
> > just
> > > > commenting on existing format of READMEs.
> > > >
> > > > I am neutral regarding separate repository with documentation. At
> > least at
> > > > the moment, I need to sleep with the idea (more).
> > > >
> > > > Some if not all READMES will stay in the repository and I was
> > suggesting
> > > > reformatting them.
> > > >
> > > > Am Fr., 17. Juli 2020 um 17:59 Uhr schrieb Matias N. :
> > > >
> > > > >
> > > > > > What I think would be great, is to pick any of this two standards.
> > > > >
> > > > > What I was trying to convey in my previous e-mail is that we can
> > choose
> > > > > Markdown for READMEs (the prefered choice, IMHO) and either
> > Markdown, RST,
> > > > > or anything else for the eventual doc-repo. These are independent
> > choices,
> > > > > one does not have to affect the other. In fact, maybe RST is better
> > for the
> > > > > doc-repo, since it supports richer syntax more apropriate for
> > building
> > > > > documentation.
> > > > >
> > > > > Best,
> > > > > Matias
> > > >
> >
> 
> 
> -- 
> Adam Feuer 
> 

Re: Markdown READMEs?

[Adam Feuer]

A few comments:

   - It would be great to have the documentation in the same repository, to
   make synchronizing a particular documentation version with the code.
   - Or if we don't do that, have some other explicit versioning that
  matches the code, and do simultaneous releases. Code and docs
synchronized
  will make peoples' lives a lot easier.
   - RST is as readable in plain text format as Markdown, and is also
   rendered automatically by Github (example rendered by Github
   
;
   raw version
   

   ).
   - The main difference between RST and Markdown formatting is the way
   links are handled. RST has a different link format and also has support for
   internal linking– in my opinion that's what makes RST really good for
   technical documentation.
   - Converting READMEs to RST or Markdown can be done manually or
   semi-manually, it's not that hard. We could design a system that included
   both text and RST or Markdown to support the transition.
   - Sphinx supports generating documentation using both RST and Markdown
   (recommonmark) so
   you can mix them.

I think getting our docs and READMEs into a single system using RST or
RST/Markdown would be great.

-adam

On Fri, Jul 17, 2020 at 9:23 AM Abdelatif Guettouche <
abdelatif.guettou...@gmail.com> wrote:

> It would be great to have READMEs in Markdown, as said before, it's
> still plain text and can be rendered by other tools/websites.  Because
> it was brought out, VIM also has plugins for syntax highlighting,
> instant rendering, etc.
> It was also suggested to use Markdown for release notes.
>
> On Fri, Jul 17, 2020 at 5:12 PM Matias N.  wrote:
> >
> > No problem, just wanted to clear any possible confusion when considering
> the idea.
> >
> > On Fri, Jul 17, 2020, at 13:09, Maciej Wójcik wrote:
> > > Sure, Matias. I was not addressing your proposition in any way. I was
> just
> > > commenting on existing format of READMEs.
> > >
> > > I am neutral regarding separate repository with documentation. At
> least at
> > > the moment, I need to sleep with the idea (more).
> > >
> > > Some if not all READMES will stay in the repository and I was
> suggesting
> > > reformatting them.
> > >
> > > Am Fr., 17. Juli 2020 um 17:59 Uhr schrieb Matias N. :
> > >
> > > >
> > > > > What I think would be great, is to pick any of this two standards.
> > > >
> > > > What I was trying to convey in my previous e-mail is that we can
> choose
> > > > Markdown for READMEs (the prefered choice, IMHO) and either
> Markdown, RST,
> > > > or anything else for the eventual doc-repo. These are independent
> choices,
> > > > one does not have to affect the other. In fact, maybe RST is better
> for the
> > > > doc-repo, since it supports richer syntax more apropriate for
> building
> > > > documentation.
> > > >
> > > > Best,
> > > > Matias
> > >
>


-- 
Adam Feuer 

Re: Markdown READMEs?

[Abdelatif Guettouche]

It would be great to have READMEs in Markdown, as said before, it's
still plain text and can be rendered by other tools/websites.  Because
it was brought out, VIM also has plugins for syntax highlighting,
instant rendering, etc.
It was also suggested to use Markdown for release notes.

On Fri, Jul 17, 2020 at 5:12 PM Matias N.  wrote:
>
> No problem, just wanted to clear any possible confusion when considering the 
> idea.
>
> On Fri, Jul 17, 2020, at 13:09, Maciej Wójcik wrote:
> > Sure, Matias. I was not addressing your proposition in any way. I was just
> > commenting on existing format of READMEs.
> >
> > I am neutral regarding separate repository with documentation. At least at
> > the moment, I need to sleep with the idea (more).
> >
> > Some if not all READMES will stay in the repository and I was suggesting
> > reformatting them.
> >
> > Am Fr., 17. Juli 2020 um 17:59 Uhr schrieb Matias N. :
> >
> > >
> > > > What I think would be great, is to pick any of this two standards.
> > >
> > > What I was trying to convey in my previous e-mail is that we can choose
> > > Markdown for READMEs (the prefered choice, IMHO) and either Markdown, RST,
> > > or anything else for the eventual doc-repo. These are independent choices,
> > > one does not have to affect the other. In fact, maybe RST is better for 
> > > the
> > > doc-repo, since it supports richer syntax more apropriate for building
> > > documentation.
> > >
> > > Best,
> > > Matias
> >

Re: Markdown READMEs?

[Matias N.]

No problem, just wanted to clear any possible confusion when considering the 
idea.

On Fri, Jul 17, 2020, at 13:09, Maciej Wójcik wrote:
> Sure, Matias. I was not addressing your proposition in any way. I was just
> commenting on existing format of READMEs.
> 
> I am neutral regarding separate repository with documentation. At least at
> the moment, I need to sleep with the idea (more).
> 
> Some if not all READMES will stay in the repository and I was suggesting
> reformatting them.
> 
> Am Fr., 17. Juli 2020 um 17:59 Uhr schrieb Matias N. :
> 
> >
> > > What I think would be great, is to pick any of this two standards.
> >
> > What I was trying to convey in my previous e-mail is that we can choose
> > Markdown for READMEs (the prefered choice, IMHO) and either Markdown, RST,
> > or anything else for the eventual doc-repo. These are independent choices,
> > one does not have to affect the other. In fact, maybe RST is better for the
> > doc-repo, since it supports richer syntax more apropriate for building
> > documentation.
> >
> > Best,
> > Matias
> 

Re: Markdown READMEs?

[Maciej Wójcik]

Sure, Matias. I was not addressing your proposition in any way. I was just
commenting on existing format of READMEs.

I am neutral regarding separate repository with documentation. At least at
the moment, I need to sleep with the idea (more).

Some if not all READMES will stay in the repository and I was suggesting
reformatting them.

Am Fr., 17. Juli 2020 um 17:59 Uhr schrieb Matias N. :

>
> > What I think would be great, is to pick any of this two standards.
>
> What I was trying to convey in my previous e-mail is that we can choose
> Markdown for READMEs (the prefered choice, IMHO) and either Markdown, RST,
> or anything else for the eventual doc-repo. These are independent choices,
> one does not have to affect the other. In fact, maybe RST is better for the
> doc-repo, since it supports richer syntax more apropriate for building
> documentation.
>
> Best,
> Matias

Re: Markdown READMEs?

[Matias N.]

> What I think would be great, is to pick any of this two standards.

What I was trying to convey in my previous e-mail is that we can choose 
Markdown for READMEs (the prefered choice, IMHO) and either Markdown, RST, or 
anything else for the eventual doc-repo. These are independent choices, one 
does not have to affect the other. In fact, maybe RST is better for the 
doc-repo, since it supports richer syntax more apropriate for building 
documentation.

Best,
Matias

Re: Markdown READMEs?

[Maciej Wójcik]

Regarding Markdown:

I don't feel like I contribute here enough to have meaningful vote, but:

Readmes in Markdown are present in almost every GitHub, GitLab project. In
particular in almost every Python, Node.js, React/Angular/Vue project.

Also quiclky looking at some C projects
- https://github.com/lvgl/lvgl/blob/master/README.md
- https://github.com/ARMmbed/littlefs/blob/master/README.md
- https://github.com/warmcat/libwebsockets/blob/master/README.md

`.md` extension stands for Markdown.

It seems to be the de-facto standard.

> Plain text is the best on cmd line environments (ssh/putty)

Markdown is still a plain text.

> I would second that: (1) plain text with no embedded tags, and (2) no new
tools.

No new tools are required. The only difference is that some editors and
GitHub will display it in more readable way.

It is almost like the previous text format that is already in the repo, it
is just standardized and widely adopted.

Syntax is non intrusive. It clearly separates code fragments with
backticks. Renders headers and lists in a more readable way. Allows for a
table, image and clickable link from time to time.

It also allows separating code fragments and then it enables
syntax-highlighting. This improves readability greatly.

The format is actually simpler than the current one.


Regarding RST format:

It is a similar concept. It just seems to be a little bit more complex
to help writing documentation of code in larger projects. I am seeing it
for the first time, but I am also happy to help
with Adam Feuer effort if you would decide to use this one.


What I think would be great, is to pick any of this two standards. I was
trying to parse existing documentation how it is now and it is problematic.
The conventions
are not always followed and fragments of code randomly glue to text when I
am trying to retrieve paragraphs from it. My parsing issue is not relevant,
but standardization is important.
And Markdown is more readable, thanks to support from modern tools like
VSCode or GitHub/Lab. While still being readable in Vim through SSH.


Am Fr., 17. Juli 2020 um 16:49 Uhr schrieb Matias N. :

> Markdown is designed to be readable in plain-text.
> I think the only thing you could consider a special tag is how links are
> handled:
> [link text](url)
> linking to images is the same, with a prefix "!".
> Everything else is actually intuitive from looking at the text itself.
> Look here:
> https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
>
> Regarding using READMEs as the backend for the main NuttX documentation,
> as I mentioned this is not the best idea because it would indeed require
> adding extra tags (like links to images, etc). READMEs should be used for
> technical information to be read when entering a subdirectory.
>
> On the other hand, Markdown or any other more complete format (like
> ReStructuredText) is a very good format for maintaining documentation
> outside of the main nuttx repo. In this case, a doc-repo with CI could be
> maintained, exactly the same as the nuttx website repo (in fact, it could
> be the same one). The website already requires ruby (jekyll) to be built.
>
> So, in summation:
> - I would use Markdown (without unnecessary tags) on the READMEs
> - I would start a doc repo (or reuse the website repo) and create a nice
> looking documentation (accessible as subdirectory or subdomain of nuttx
> website) based on Markdown or any other useful format and some website
> generator like readthedocs or whatever works best.
>
> Best,
> Matias
>
> On Fri, Jul 17, 2020, at 11:38, Alin Jerpelea wrote:
> > +1
> >
> > Plain text is the best on cmd line environments (ssh/putty)
> >
> > On Fri, Jul 17, 2020, 16:28 Gregory Nutt  wrote:
> >
> > >
> > > > 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
> > > I would second that:  (1) plain text with no embedded tags, and (2) no
> > > new tools.
> > >
> >
>

Re: Markdown READMEs?

[Matias N.]

Markdown is designed to be readable in plain-text.
I think the only thing you could consider a special tag is how links are 
handled:
[link text](url)
linking to images is the same, with a prefix "!".
Everything else is actually intuitive from looking at the text itself.
Look here: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet

Regarding using READMEs as the backend for the main NuttX documentation, as I 
mentioned this is not the best idea because it would indeed require adding 
extra tags (like links to images, etc). READMEs should be used for technical 
information to be read when entering a subdirectory.

On the other hand, Markdown or any other more complete format (like 
ReStructuredText) is a very good format for maintaining documentation outside 
of the main nuttx repo. In this case, a doc-repo with CI could be maintained, 
exactly the same as the nuttx website repo (in fact, it could be the same one). 
The website already requires ruby (jekyll) to be built.

So, in summation:
- I would use Markdown (without unnecessary tags) on the READMEs
- I would start a doc repo (or reuse the website repo) and create a nice 
looking documentation (accessible as subdirectory or subdomain of nuttx 
website) based on Markdown or any other useful format and some website 
generator like readthedocs or whatever works best.

Best,
Matias

On Fri, Jul 17, 2020, at 11:38, Alin Jerpelea wrote:
> +1
> 
> Plain text is the best on cmd line environments (ssh/putty)
> 
> On Fri, Jul 17, 2020, 16:28 Gregory Nutt  wrote:
> 
> >
> > > 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
> > I would second that:  (1) plain text with no embedded tags, and (2) no
> > new tools.
> >
> 

Re: Markdown READMEs?

[Alin Jerpelea]

+1

Plain text is the best on cmd line environments (ssh/putty)

On Fri, Jul 17, 2020, 16:28 Gregory Nutt  wrote:

>
> > 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
> I would second that:  (1) plain text with no embedded tags, and (2) no
> new tools.
>

Re: Markdown READMEs?

[Gregory Nutt]

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 
I would second that:  (1) plain text with no embedded tags, and (2) no 
new tools.

Re: Markdown READMEs?

[Sebastien Lorquet]

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

Re: Markdown READMEs?

[Adam Feuer]

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

Re: Markdown READMEs?

[Matias N.]

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  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?

[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