You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@nuttx.apache.org by "Matias N." <ma...@imap.cc> on 2020/07/16 01:27:01 UTC
Markdown READMEs?
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
Re: Markdown READMEs?
Posted by Justin Mclean <ju...@classsoftware.com>.
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?
Posted by Brennan Ashton <ba...@brennanashton.com>.
On Sun, Jul 19, 2020 at 9:27 PM Matias N. <ma...@imap.cc> 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?
Posted by "Matias N." <ma...@imap.cc>.
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. <ma...@imap.cc> 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?
Posted by Brennan Ashton <ba...@brennanashton.com>.
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. <ma...@imap.cc> 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?
Posted by "Matias N." <ma...@imap.cc>.
> 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?
Posted by "Matias N." <ma...@imap.cc>.
On Mon, Jul 20, 2020, at 19:13, Adam Feuer wrote:
> Matias,
>
> Yes, pandoc can convert to and from RST, Markdown, and HTML. (Lots of other formats too.) It doesn't do a great job with internal links and formatting. But it's better than starting from scratch.
I just tried with the Coding style HTML and does a reasonable job. At least it saves a lot of work.
> Should we make a git branch somewhere so we can collaborate? Your structure looks great.
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.
>
> Re: boards, it would be great if we could follow something like what Zephyr does— their board Readme gets picked up by the sphinx build out of the board's doc/ directory. That way you can put whatever images, etc. in that board directory.
Yes, having board READMEs in RST format definitely simplifies building the docs from them. However, this would imply that the requirement expressed by other users that READMEs remain easy to read directly would not be met. Hence my proposal to document the boards explicitly inside the documentation directory (migrating most of the existing content in the READMEs) and leave those READMEs in Markdown with only minimal content. I guess this point requires further discussion and input from other members.
Best,
Matias
> -adam
>
>
>
> On Mon, Jul 20, 2020 at 2:37 PM Matias N. <ma...@imap.cc> wrote:
>> __
>> Hi,
>> seems we both had the same idea, I also started playing with Sphinx locally. In my case
>> i focused on finding a nice configuration for Sphinx. It looks like this on my side:
>>
>>
>> On Mon, Jul 20, 2020, at 18:23, Adam Feuer wrote:
>>> 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.
>>
>> If we include the docs in the main repo (which would seem is the preference from the
>> previous replies to this thread) I would aim for eventually migrating the HTML docs to this system
>> so it would replace the content of Documentation in the end.
>>
>>>
>>> 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.
>>
>> So the HTML were converted in RST automatically? Didn't know you could do that, that is
>> a great help to get a reasonable first version which can later be improved manually.
>> I think that we should also think a bit more in a nice index for the docs and then start placing/adapting
>> the existing content from the different sources (HTMLs, Wiki, companion, board READMEs, etc.). As an example,
>> my index.rst looks like this:
>>
>> introduction/index.rst
>> quickstart/index.rst
>> reference/index.rst
>> boards/index.rst
>> guides/index.rst
>> releases/index.rst
>> contribute/index.rst
>>
>>>
>>> I'll add an example Markdown file here so we can look at how the mixed
>>> ReStructuredText / Markdown stuff looks together.
>>
>> While playing with Sphinx I kept wondering if simply including board READMEs as part of the boards
>> was the best approach. Maybe it is a good first step to get all content exposed in one place. But if we want
>> board pictures and so on, it may be better to leave this kind of documentation inside Documentation. In that case
>> the board READMEs (inside boards/) would not need to be as verbose and only include any required technical details.
>>
>> Best,
>> Matias
>>
>>> -adam
>>>
>>> On Mon, Jul 20, 2020 at 2:26 AM Xiang Xiao <xi...@gmail.com>
>>> 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. <ma...@imap.cc>
>>> > > 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 <ad...@starcat.io>
>>>
>>
>
>
> --
> Adam Feuer <ad...@starcat.io>
>
> *Attachments:*
> * image.png
Re: Markdown READMEs?
Posted by Adam Feuer <ad...@starcat.io>.
Matias,
Yes, pandoc can convert to and from RST, Markdown, and HTML. (Lots of other
formats too.) It doesn't do a great job with internal links and formatting.
But it's better than starting from scratch.
Should we make a git branch somewhere so we can collaborate? Your structure
looks great.
Re: boards, it would be great if we could follow something like what Zephyr
does— their board Readme gets picked up by the sphinx build out of the
board's doc/ directory. That way you can put whatever images, etc. in that
board directory.
-adam
On Mon, Jul 20, 2020 at 2:37 PM Matias N. <ma...@imap.cc> wrote:
> Hi,
> seems we both had the same idea, I also started playing with Sphinx
> locally. In my case
> i focused on finding a nice configuration for Sphinx. It looks like this
> on my side:
>
>
> On Mon, Jul 20, 2020, at 18:23, Adam Feuer wrote:
>
> 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.
>
>
> If we include the docs in the main repo (which would seem is the
> preference from the
> previous replies to this thread) I would aim for eventually migrating the
> HTML docs to this system
> so it would replace the content of Documentation in the end.
>
>
> 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.
>
>
> So the HTML were converted in RST automatically? Didn't know you could do
> that, that is
> a great help to get a reasonable first version which can later be improved
> manually.
> I think that we should also think a bit more in a nice index for the docs
> and then start placing/adapting
> the existing content from the different sources (HTMLs, Wiki, companion,
> board READMEs, etc.). As an example,
> my index.rst looks like this:
>
> introduction/index.rst
> quickstart/index.rst
> reference/index.rst
> boards/index.rst
> guides/index.rst
> releases/index.rst
> contribute/index.rst
>
>
> I'll add an example Markdown file here so we can look at how the mixed
> ReStructuredText / Markdown stuff looks together.
>
>
> While playing with Sphinx I kept wondering if simply including board
> READMEs as part of the boards
> was the best approach. Maybe it is a good first step to get all content
> exposed in one place. But if we want
> board pictures and so on, it may be better to leave this kind of
> documentation inside Documentation. In that case
> the board READMEs (inside boards/) would not need to be as verbose and
> only include any required technical details.
>
> Best,
> Matias
>
> -adam
>
> On Mon, Jul 20, 2020 at 2:26 AM Xiang Xiao <xi...@gmail.com>
> 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. <ma...@imap.cc>
> > > 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 <ad...@starcat.io>
>
>
>
--
Adam Feuer <ad...@starcat.io>
Re: Markdown READMEs?
Posted by Adam Feuer <ad...@starcat.io>.
On Mon, Jul 20, 2020 at 4:32 PM Justin Mclean <ju...@classsoftware.com>
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 <ad...@starcat.io>
Re: Markdown READMEs?
Posted by Justin Mclean <ju...@classsoftware.com>.
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?
Posted by Adam Feuer <ad...@starcat.io>.
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 <ha...@gmail.com>
wrote:
> On Mon, Jul 20, 2020 at 7:07 PM Gregory Nutt <sp...@gmail.com> 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 <ad...@starcat.io>
Re: Markdown READMEs?
Posted by Nathan Hartman <ha...@gmail.com>.
On Mon, Jul 20, 2020 at 7:07 PM Gregory Nutt <sp...@gmail.com> 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?
Posted by Xiang Xiao <xi...@gmail.com>.
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 <sp...@gmail.com>
> 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?
Posted by Gregory Nutt <sp...@gmail.com>.
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?
Posted by Maciej Wójcik <w8...@gmail.com>.
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 <ad...@starcat.io>:
> 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. <ma...@imap.cc> 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><version>
> > 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 <
> > bashton@brennanashton.com>
> > >> wrote:
> > >>
> > >> > On Tue, Jul 21, 2020, 10:51 AM Adam Feuer <ad...@starcat.io> 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 <ad...@starcat.io>
> > >>
> > >
> >
>
>
> --
> Adam Feuer <ad...@starcat.io>
>
Re: Markdown READMEs?
Posted by Adam Feuer <ad...@starcat.io>.
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. <ma...@imap.cc> 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><version>
> 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 <
> bashton@brennanashton.com>
> >> wrote:
> >>
> >> > On Tue, Jul 21, 2020, 10:51 AM Adam Feuer <ad...@starcat.io> 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 <ad...@starcat.io>
> >>
> >
>
--
Adam Feuer <ad...@starcat.io>
Re: Markdown READMEs?
Posted by "Matias N." <ma...@imap.cc>.
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><version>
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 <ba...@brennanashton.com>
>> wrote:
>>
>> > On Tue, Jul 21, 2020, 10:51 AM Adam Feuer <ad...@starcat.io> 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 <ad...@starcat.io>
>>
>
Re: Markdown READMEs?
Posted by "Matias N." <ma...@imap.cc>.
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 <ba...@brennanashton.com>
> wrote:
>
> > On Tue, Jul 21, 2020, 10:51 AM Adam Feuer <ad...@starcat.io> 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 <ad...@starcat.io>
>
Re: Markdown READMEs?
Posted by Adam Feuer <ad...@starcat.io>.
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 <ba...@brennanashton.com>
wrote:
> On Tue, Jul 21, 2020, 10:51 AM Adam Feuer <ad...@starcat.io> 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 <ad...@starcat.io>
Re: Markdown READMEs?
Posted by Brennan Ashton <ba...@brennanashton.com>.
On Tue, Jul 21, 2020, 10:51 AM Adam Feuer <ad...@starcat.io> 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?
Posted by Adam Feuer <ad...@starcat.io>.
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
On Mon, Jul 20, 2020 at 3:59 PM Adam Feuer <ad...@starcat.io> wrote:
> Matias,
>
> 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.
>
> -adam
>
>
> On Mon, Jul 20, 2020 at 3:45 PM Maciej Wójcik <w8...@gmail.com> wrote:
>
>> 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
>>
>> Not sure if you need `apps` repository right now.
>> Just in case, it is a `master` branch of this fork
>> https://github.com/w8jcik/incubator-nuttx-apps
>>
>> Am Mo., 20. Juli 2020 um 23:37 Uhr schrieb Matias N. <ma...@imap.cc>:
>>
>>> Hi,
>>> seems we both had the same idea, I also started playing with Sphinx
>>> locally. In my case
>>> i focused on finding a nice configuration for Sphinx. It looks like this
>>> on my side:
>>>
>>>
>>> On Mon, Jul 20, 2020, at 18:23, Adam Feuer wrote:
>>>
>>> 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.
>>>
>>>
>>> If we include the docs in the main repo (which would seem is the
>>> preference from the
>>> previous replies to this thread) I would aim for eventually migrating
>>> the HTML docs to this system
>>> so it would replace the content of Documentation in the end.
>>>
>>>
>>> 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.
>>>
>>>
>>> So the HTML were converted in RST automatically? Didn't know you could
>>> do that, that is
>>> a great help to get a reasonable first version which can later be
>>> improved manually.
>>> I think that we should also think a bit more in a nice index for the
>>> docs and then start placing/adapting
>>> the existing content from the different sources (HTMLs, Wiki, companion,
>>> board READMEs, etc.). As an example,
>>> my index.rst looks like this:
>>>
>>> introduction/index.rst
>>> quickstart/index.rst
>>> reference/index.rst
>>> boards/index.rst
>>> guides/index.rst
>>> releases/index.rst
>>> contribute/index.rst
>>>
>>>
>>> I'll add an example Markdown file here so we can look at how the mixed
>>> ReStructuredText / Markdown stuff looks together.
>>>
>>>
>>> While playing with Sphinx I kept wondering if simply including board
>>> READMEs as part of the boards
>>> was the best approach. Maybe it is a good first step to get all content
>>> exposed in one place. But if we want
>>> board pictures and so on, it may be better to leave this kind of
>>> documentation inside Documentation. In that case
>>> the board READMEs (inside boards/) would not need to be as verbose and
>>> only include any required technical details.
>>>
>>> Best,
>>> Matias
>>>
>>> -adam
>>>
>>> On Mon, Jul 20, 2020 at 2:26 AM Xiang Xiao <xi...@gmail.com>
>>> 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. <ma...@imap.cc>
>>> > > 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 <ad...@starcat.io>
>>>
>>>
>>>
>
> --
> Adam Feuer <ad...@starcat.io>
>
--
Adam Feuer <ad...@starcat.io>
Re: Markdown READMEs?
Posted by Gregory Nutt <sp...@gmail.com>.
> 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?
Posted by Adam Feuer <ad...@starcat.io>.
Matias,
Ok, I'll make a PR against your repo tomorrow.
Re: github/readthedocs, yeah github is better, I just had an existing setup
for Read The Docs, so it took little effort. I'm good with changing to
github once we figure it out.
-adam
On Mon, Jul 20, 2020 at 5:51 PM Matias N. <ma...@imap.cc> wrote:
> On Mon, Jul 20, 2020, at 19:59, Adam Feuer wrote:
>
> Matias,
>
> 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.
>
>
> Yes, there is a "docs" branch (
> https://github.com/v01d/incubator-nuttx/tree/docs). I've placed sphinx
> documentation in /doc. You can make the PR against that branch.
>
> 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.
>
>
> That's a good idea. I also feel it is good to have something to show.
> It would be good to also try to setup GitHub CI so that docs are generated
> there directly, but otherwise we can use readthedocs in the meantime.
>
> Best,
> Matias
>
>
> -adam
>
>
> On Mon, Jul 20, 2020 at 3:45 PM Maciej Wójcik <w8...@gmail.com> wrote:
>
> 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
>
> Not sure if you need `apps` repository right now.
> Just in case, it is a `master` branch of this fork
> https://github.com/w8jcik/incubator-nuttx-apps
>
> Am Mo., 20. Juli 2020 um 23:37 Uhr schrieb Matias N. <ma...@imap.cc>:
>
>
> Hi,
> seems we both had the same idea, I also started playing with Sphinx
> locally. In my case
> i focused on finding a nice configuration for Sphinx. It looks like this
> on my side:
>
>
> On Mon, Jul 20, 2020, at 18:23, Adam Feuer wrote:
>
> 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.
>
>
> If we include the docs in the main repo (which would seem is the
> preference from the
> previous replies to this thread) I would aim for eventually migrating the
> HTML docs to this system
> so it would replace the content of Documentation in the end.
>
>
> 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.
>
>
> So the HTML were converted in RST automatically? Didn't know you could do
> that, that is
> a great help to get a reasonable first version which can later be improved
> manually.
> I think that we should also think a bit more in a nice index for the docs
> and then start placing/adapting
> the existing content from the different sources (HTMLs, Wiki, companion,
> board READMEs, etc.). As an example,
> my index.rst looks like this:
>
> introduction/index.rst
> quickstart/index.rst
> reference/index.rst
> boards/index.rst
> guides/index.rst
> releases/index.rst
> contribute/index.rst
>
>
> I'll add an example Markdown file here so we can look at how the mixed
> ReStructuredText / Markdown stuff looks together.
>
>
> While playing with Sphinx I kept wondering if simply including board
> READMEs as part of the boards
> was the best approach. Maybe it is a good first step to get all content
> exposed in one place. But if we want
> board pictures and so on, it may be better to leave this kind of
> documentation inside Documentation. In that case
> the board READMEs (inside boards/) would not need to be as verbose and
> only include any required technical details.
>
> Best,
> Matias
>
> -adam
>
> On Mon, Jul 20, 2020 at 2:26 AM Xiang Xiao <xi...@gmail.com>
> 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. <ma...@imap.cc>
> > > 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 <ad...@starcat.io>
>
>
>
>
> --
> Adam Feuer <ad...@starcat.io>
>
> *Attachments:*
>
> - image.png
>
>
>
--
Adam Feuer <ad...@starcat.io>
Re: Markdown READMEs?
Posted by "Matias N." <ma...@imap.cc>.
On Mon, Jul 20, 2020, at 19:59, Adam Feuer wrote:
> Matias,
>
> 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.
Yes, there is a "docs" branch (https://github.com/v01d/incubator-nuttx/tree/docs). I've placed sphinx documentation in /doc. You can make the PR against that branch.
> 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.
That's a good idea. I also feel it is good to have something to show.
It would be good to also try to setup GitHub CI so that docs are generated there directly, but otherwise we can use readthedocs in the meantime.
Best,
Matias
>
> -adam
>
>
> On Mon, Jul 20, 2020 at 3:45 PM Maciej Wójcik <w8...@gmail.com> wrote:
>> 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
>>
>> Not sure if you need `apps` repository right now.
>> Just in case, it is a `master` branch of this fork https://github.com/w8jcik/incubator-nuttx-apps
>>
>> Am Mo., 20. Juli 2020 um 23:37 Uhr schrieb Matias N. <ma...@imap.cc>:
>>> __
>>> Hi,
>>> seems we both had the same idea, I also started playing with Sphinx locally. In my case
>>> i focused on finding a nice configuration for Sphinx. It looks like this on my side:
>>>
>>>
>>> On Mon, Jul 20, 2020, at 18:23, Adam Feuer wrote:
>>>> 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.
>>>
>>> If we include the docs in the main repo (which would seem is the preference from the
>>> previous replies to this thread) I would aim for eventually migrating the HTML docs to this system
>>> so it would replace the content of Documentation in the end.
>>>
>>>>
>>>> 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.
>>>
>>> So the HTML were converted in RST automatically? Didn't know you could do that, that is
>>> a great help to get a reasonable first version which can later be improved manually.
>>> I think that we should also think a bit more in a nice index for the docs and then start placing/adapting
>>> the existing content from the different sources (HTMLs, Wiki, companion, board READMEs, etc.). As an example,
>>> my index.rst looks like this:
>>>
>>> introduction/index.rst
>>> quickstart/index.rst
>>> reference/index.rst
>>> boards/index.rst
>>> guides/index.rst
>>> releases/index.rst
>>> contribute/index.rst
>>>
>>>>
>>>> I'll add an example Markdown file here so we can look at how the mixed
>>>> ReStructuredText / Markdown stuff looks together.
>>>
>>> While playing with Sphinx I kept wondering if simply including board READMEs as part of the boards
>>> was the best approach. Maybe it is a good first step to get all content exposed in one place. But if we want
>>> board pictures and so on, it may be better to leave this kind of documentation inside Documentation. In that case
>>> the board READMEs (inside boards/) would not need to be as verbose and only include any required technical details.
>>>
>>> Best,
>>> Matias
>>>
>>>> -adam
>>>>
>>>> On Mon, Jul 20, 2020 at 2:26 AM Xiang Xiao <xi...@gmail.com>
>>>> 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. <ma...@imap.cc>
>>>> > > 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 <ad...@starcat.io>
>>>>
>>>
>
>
> --
> Adam Feuer <ad...@starcat.io>
>
> *Attachments:*
> * image.png
Re: Markdown READMEs?
Posted by Adam Feuer <ad...@starcat.io>.
Matias,
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.
-adam
On Mon, Jul 20, 2020 at 3:45 PM Maciej Wójcik <w8...@gmail.com> wrote:
> 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
>
> Not sure if you need `apps` repository right now.
> Just in case, it is a `master` branch of this fork
> https://github.com/w8jcik/incubator-nuttx-apps
>
> Am Mo., 20. Juli 2020 um 23:37 Uhr schrieb Matias N. <ma...@imap.cc>:
>
>> Hi,
>> seems we both had the same idea, I also started playing with Sphinx
>> locally. In my case
>> i focused on finding a nice configuration for Sphinx. It looks like this
>> on my side:
>>
>>
>> On Mon, Jul 20, 2020, at 18:23, Adam Feuer wrote:
>>
>> 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.
>>
>>
>> If we include the docs in the main repo (which would seem is the
>> preference from the
>> previous replies to this thread) I would aim for eventually migrating the
>> HTML docs to this system
>> so it would replace the content of Documentation in the end.
>>
>>
>> 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.
>>
>>
>> So the HTML were converted in RST automatically? Didn't know you could do
>> that, that is
>> a great help to get a reasonable first version which can later be
>> improved manually.
>> I think that we should also think a bit more in a nice index for the docs
>> and then start placing/adapting
>> the existing content from the different sources (HTMLs, Wiki, companion,
>> board READMEs, etc.). As an example,
>> my index.rst looks like this:
>>
>> introduction/index.rst
>> quickstart/index.rst
>> reference/index.rst
>> boards/index.rst
>> guides/index.rst
>> releases/index.rst
>> contribute/index.rst
>>
>>
>> I'll add an example Markdown file here so we can look at how the mixed
>> ReStructuredText / Markdown stuff looks together.
>>
>>
>> While playing with Sphinx I kept wondering if simply including board
>> READMEs as part of the boards
>> was the best approach. Maybe it is a good first step to get all content
>> exposed in one place. But if we want
>> board pictures and so on, it may be better to leave this kind of
>> documentation inside Documentation. In that case
>> the board READMEs (inside boards/) would not need to be as verbose and
>> only include any required technical details.
>>
>> Best,
>> Matias
>>
>> -adam
>>
>> On Mon, Jul 20, 2020 at 2:26 AM Xiang Xiao <xi...@gmail.com>
>> 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. <ma...@imap.cc>
>> > > 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 <ad...@starcat.io>
>>
>>
>>
--
Adam Feuer <ad...@starcat.io>
Re: Markdown READMEs?
Posted by Gregory Nutt <sp...@gmail.com>.
> 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?
Posted by "Matias N." <ma...@imap.cc>.
Nice work!
On Mon, Jul 20, 2020, at 19:45, Maciej Wójcik wrote:
> 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
>
> Not sure if you need `apps` repository right now.
> Just in case, it is a `master` branch of this fork https://github.com/w8jcik/incubator-nuttx-apps
>
> Am Mo., 20. Juli 2020 um 23:37 Uhr schrieb Matias N. <ma...@imap.cc>:
>> __
>> Hi,
>> seems we both had the same idea, I also started playing with Sphinx locally. In my case
>> i focused on finding a nice configuration for Sphinx. It looks like this on my side:
>>
>>
>> On Mon, Jul 20, 2020, at 18:23, Adam Feuer wrote:
>>> 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.
>>
>> If we include the docs in the main repo (which would seem is the preference from the
>> previous replies to this thread) I would aim for eventually migrating the HTML docs to this system
>> so it would replace the content of Documentation in the end.
>>
>>>
>>> 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.
>>
>> So the HTML were converted in RST automatically? Didn't know you could do that, that is
>> a great help to get a reasonable first version which can later be improved manually.
>> I think that we should also think a bit more in a nice index for the docs and then start placing/adapting
>> the existing content from the different sources (HTMLs, Wiki, companion, board READMEs, etc.). As an example,
>> my index.rst looks like this:
>>
>> introduction/index.rst
>> quickstart/index.rst
>> reference/index.rst
>> boards/index.rst
>> guides/index.rst
>> releases/index.rst
>> contribute/index.rst
>>
>>>
>>> I'll add an example Markdown file here so we can look at how the mixed
>>> ReStructuredText / Markdown stuff looks together.
>>
>> While playing with Sphinx I kept wondering if simply including board READMEs as part of the boards
>> was the best approach. Maybe it is a good first step to get all content exposed in one place. But if we want
>> board pictures and so on, it may be better to leave this kind of documentation inside Documentation. In that case
>> the board READMEs (inside boards/) would not need to be as verbose and only include any required technical details.
>>
>> Best,
>> Matias
>>
>>> -adam
>>>
>>> On Mon, Jul 20, 2020 at 2:26 AM Xiang Xiao <xi...@gmail.com>
>>> 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. <ma...@imap.cc>
>>> > > 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 <ad...@starcat.io>
>>>
>>
>
> *Attachments:*
> * image.png
Re: Markdown READMEs?
Posted by Maciej Wójcik <w8...@gmail.com>.
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
Not sure if you need `apps` repository right now.
Just in case, it is a `master` branch of this fork
https://github.com/w8jcik/incubator-nuttx-apps
Am Mo., 20. Juli 2020 um 23:37 Uhr schrieb Matias N. <ma...@imap.cc>:
> Hi,
> seems we both had the same idea, I also started playing with Sphinx
> locally. In my case
> i focused on finding a nice configuration for Sphinx. It looks like this
> on my side:
>
>
> On Mon, Jul 20, 2020, at 18:23, Adam Feuer wrote:
>
> 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.
>
>
> If we include the docs in the main repo (which would seem is the
> preference from the
> previous replies to this thread) I would aim for eventually migrating the
> HTML docs to this system
> so it would replace the content of Documentation in the end.
>
>
> 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.
>
>
> So the HTML were converted in RST automatically? Didn't know you could do
> that, that is
> a great help to get a reasonable first version which can later be improved
> manually.
> I think that we should also think a bit more in a nice index for the docs
> and then start placing/adapting
> the existing content from the different sources (HTMLs, Wiki, companion,
> board READMEs, etc.). As an example,
> my index.rst looks like this:
>
> introduction/index.rst
> quickstart/index.rst
> reference/index.rst
> boards/index.rst
> guides/index.rst
> releases/index.rst
> contribute/index.rst
>
>
> I'll add an example Markdown file here so we can look at how the mixed
> ReStructuredText / Markdown stuff looks together.
>
>
> While playing with Sphinx I kept wondering if simply including board
> READMEs as part of the boards
> was the best approach. Maybe it is a good first step to get all content
> exposed in one place. But if we want
> board pictures and so on, it may be better to leave this kind of
> documentation inside Documentation. In that case
> the board READMEs (inside boards/) would not need to be as verbose and
> only include any required technical details.
>
> Best,
> Matias
>
> -adam
>
> On Mon, Jul 20, 2020 at 2:26 AM Xiang Xiao <xi...@gmail.com>
> 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. <ma...@imap.cc>
> > > 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 <ad...@starcat.io>
>
>
>
Re: Markdown READMEs?
Posted by "Matias N." <ma...@imap.cc>.
Hi,
seems we both had the same idea, I also started playing with Sphinx locally. In my case
i focused on finding a nice configuration for Sphinx. It looks like this on my side:
On Mon, Jul 20, 2020, at 18:23, Adam Feuer wrote:
> 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.
If we include the docs in the main repo (which would seem is the preference from the
previous replies to this thread) I would aim for eventually migrating the HTML docs to this system
so it would replace the content of Documentation in the end.
>
> 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.
So the HTML were converted in RST automatically? Didn't know you could do that, that is
a great help to get a reasonable first version which can later be improved manually.
I think that we should also think a bit more in a nice index for the docs and then start placing/adapting
the existing content from the different sources (HTMLs, Wiki, companion, board READMEs, etc.). As an example,
my index.rst looks like this:
introduction/index.rst
quickstart/index.rst
reference/index.rst
boards/index.rst
guides/index.rst
releases/index.rst
contribute/index.rst
>
> I'll add an example Markdown file here so we can look at how the mixed
> ReStructuredText / Markdown stuff looks together.
While playing with Sphinx I kept wondering if simply including board READMEs as part of the boards
was the best approach. Maybe it is a good first step to get all content exposed in one place. But if we want
board pictures and so on, it may be better to leave this kind of documentation inside Documentation. In that case
the board READMEs (inside boards/) would not need to be as verbose and only include any required technical details.
Best,
Matias
> -adam
>
> On Mon, Jul 20, 2020 at 2:26 AM Xiang Xiao <xi...@gmail.com>
> 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. <ma...@imap.cc>
> > > 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 <ad...@starcat.io>
>
Re: Markdown READMEs?
Posted by Adam Feuer <ad...@starcat.io>.
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 <xi...@gmail.com>
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. <ma...@imap.cc>
> > 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 <ad...@starcat.io>
Re: Markdown READMEs?
Posted by Bill Rees <re...@icloud.com.INVALID>.
+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. <ma...@imap.cc>
>> 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?
Posted by Xiang Xiao <xi...@gmail.com>.
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. <ma...@imap.cc>
> 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?
Posted by "Matias N." <ma...@imap.cc>.
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?
Posted by Justin Mclean <ju...@classsoftware.com>.
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?
Posted by Adam Feuer <ad...@starcat.io>.
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
<https://docs.zephyrproject.org/latest/boards/index.html>; example board
Nitrogen
<https://docs.zephyrproject.org/latest/boards/arm/96b_nitrogen/doc/index.html>;
example board nitrogen RST on github
<https://github.com/zephyrproject-rtos/zephyr/blob/master/boards/arm/96b_nitrogen/doc/index.rst>
).
-adam
--
Adam Feuer <ad...@starcat.io>
Re: Markdown READMEs?
Posted by "Matias N." <ma...@imap.cc>.
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
> <https://github.com/adamfeuer/nuttx-companion/blob/master/docs/user/install.rst>;
> raw version
> <https://raw.githubusercontent.com/adamfeuer/nuttx-companion/master/docs/user/install.rst>
> ).
> - 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) <https://www.sphinx-doc.org/en/master/usage/markdown.html>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.guettouche@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. <ma...@imap.cc> 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. <ma...@imap.cc>:
> > > >
> > > > >
> > > > > > 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 <ad...@starcat.io>
>
Re: Markdown READMEs?
Posted by Adam Feuer <ad...@starcat.io>.
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
<https://github.com/adamfeuer/nuttx-companion/blob/master/docs/user/install.rst>;
raw version
<https://raw.githubusercontent.com/adamfeuer/nuttx-companion/master/docs/user/install.rst>
).
- 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) <https://www.sphinx-doc.org/en/master/usage/markdown.html>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.guettouche@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. <ma...@imap.cc> 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. <ma...@imap.cc>:
> > >
> > > >
> > > > > 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 <ad...@starcat.io>
Re: Markdown READMEs?
Posted by Abdelatif Guettouche <ab...@gmail.com>.
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. <ma...@imap.cc> 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. <ma...@imap.cc>:
> >
> > >
> > > > 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?
Posted by "Matias N." <ma...@imap.cc>.
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. <ma...@imap.cc>:
>
> >
> > > 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?
Posted by Maciej Wójcik <w8...@gmail.com>.
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. <ma...@imap.cc>:
>
> > 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?
Posted by "Matias N." <ma...@imap.cc>.
> 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?
Posted by Maciej Wójcik <w8...@gmail.com>.
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. <ma...@imap.cc>:
> 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 <sp...@gmail.com> 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?
Posted by "Matias N." <ma...@imap.cc>.
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 <sp...@gmail.com> 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?
Posted by Alin Jerpelea <je...@gmail.com>.
+1
Plain text is the best on cmd line environments (ssh/putty)
On Fri, Jul 17, 2020, 16:28 Gregory Nutt <sp...@gmail.com> 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?
Posted by Gregory Nutt <sp...@gmail.com>.
> 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?
Posted by Sebastien Lorquet <se...@lorquet.fr>.
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. <ma...@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 <w8...@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. <ma...@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 <ad...@starcat.io>
>>>
>
Re: Markdown READMEs?
Posted by Adam Feuer <ad...@starcat.io>.
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. <ma...@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 <w8...@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. <ma...@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 <ad...@starcat.io>
> >
>
--
Adam Feuer <ad...@starcat.io>
Re: Markdown READMEs?
Posted by "Matias N." <ma...@imap.cc>.
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 <w8...@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. <ma...@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 <ad...@starcat.io>
>
Re: Markdown READMEs?
Posted by Adam Feuer <ad...@starcat.io>.
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 <w8...@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. <ma...@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 <ad...@starcat.io>
Re: Markdown READMEs?
Posted by Maciej Wójcik <w8...@gmail.com>.
> 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. <ma...@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
Re: Markdown READMEs?
Posted by "Matias N." <ma...@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
Re: Markdown READMEs?
Posted by Brennan Ashton <ba...@brennanashton.com>.
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. <ma...@imap.cc> 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