Re: Markdown READMEs?

This PR changes all READMEs in `apps` repository into Markdown https://github.com/apache/incubator-nuttx-apps/pull/337 More in the description. Am Di., 21. Juli 2020 um 20:37 Uhr schrieb Adam Feuer : > Matias, > > Yes, I have the NuttX.html file partially converted. I'll see if I can get >

Re: Markdown READMEs?

Matias, Yes, I have the NuttX.html file partially converted. I'll see if I can get that a little close today and submit a PR to your branch. -adam On Tue, Jul 21, 2020 at 11:23 AM Matias N. wrote: > Ok, got it sooner than expected. The docs are published to: >

Re: Markdown READMEs?

Ok, got it sooner than expected. The docs are published to: https://v01d.github.io/incubator-nuttx/ Right now as we're working on a "docs" branch in this fork, you can see it generated here:

Re: Markdown READMEs?

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

Re: Markdown READMEs?

On Tue, Jul 21, 2020, 10:51 AM Adam Feuer wrote: > Matias, Maciej, > > Ok, I looked into doing a Sphinx build of RST and Markdown via Github and > publishing to Github pages automatically. People have done it, but it's a > bit more complicated than I thought. I'll see if I can get it worked out

RE: Markdown READMEs?

/apache/incubator-nuttx, all issues get fixed automatically. > -Original Message- > From: Gregory Nutt > Sent: Tuesday, July 21, 2020 7:08 AM > To: dev@nuttx.apache.org > Subject: Re: Markdown READMEs? > > For those really opposed to HTML, another option is to simply

Re: Markdown READMEs?

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

Re: Markdown READMEs?

On Mon, Jul 20, 2020 at 4:32 PM Justin Mclean wrote: > That's a great idea, but it may have some impact on teh LICENSE file > depending on what libraries, fonts etc are bundled with the documentation. > You may need to make sure that nothing with an incomparable license sneaks > in. > The

Re: Markdown READMEs?

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

Re: Markdown READMEs?

I also love having the docs in the repository and releases, and versioned along with the code. It makes things so much easier. If I had to pick between the current docs (HTML/txt) and the wiki, I would pick the current docs! -adam On Mon, Jul 20, 2020 at 4:17 PM Nathan Hartman wrote: > On

Re: Markdown READMEs?

On Mon, Jul 20, 2020 at 7:07 PM Gregory Nutt wrote: > For those really opposed to HTML, another option is to simply use the > Confluence versions of the documents here: > https://cwiki.apache.org/confluence/display/NUTTX/Documentation > > These are the same documents that are currently in

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

Re: Markdown READMEs?

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,

Re: Markdown READMEs?

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 -

Re: Markdown READMEs?

> 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

Re: Markdown READMEs?

From: Matias N. > > Sent: Monday, July 20, 2020 11:39 AM > > To: dev@nuttx.apache.org > > Subject: Re: Markdown READMEs? > > > > Hi, > > after reading all responses I would propose to: > > > > 1. use Markdown for all READMEs: the syntax is simple an

Re: Markdown READMEs?

rg 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 thi

RE: Markdown READMEs?

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 R

Re: Markdown READMEs?

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

Re: Markdown READMEs?

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

Re: Markdown READMEs?

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

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

Re: Markdown READMEs?

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?

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,

Re: Markdown READMEs?

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 >

Re: Markdown READMEs?

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

Re: Markdown READMEs?

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

Re: Markdown READMEs?

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

Re: Markdown READMEs?

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

Re: Markdown READMEs?

> 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

Re: Markdown READMEs?

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 -

Re: Markdown READMEs?

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:

Re: Markdown READMEs?

+1 Plain text is the best on cmd line environments (ssh/putty) On Fri, Jul 17, 2020, 16:28 Gregory Nutt wrote: > > > Please make sure the readmes are still easily readable in vim and > > other plain text editors. > > > > Plain text is good. > > > > underlined plain text interpreted by github

Re: Markdown READMEs?

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,

Re: Markdown READMEs?

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,

Re: Markdown READMEs?

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

Re: Markdown READMEs?

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

Re: Markdown READMEs?

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?

Zephyr uses Sphinx and ReStructured Text (RST) for their docs. I'm a fan obviously, it's great for writing hyperlinked technical documentation. Sphinx requires Python, though. The board list with pictures is a great

Re: Markdown READMEs?

> 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

Re: Markdown READMEs?

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 >

Re: Markdown READMEs?

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

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