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.guettou...@gmail.com> wrote: > It would be great to have READMEs in Markdown, as said before, it's > still plain text and can be rendered by other tools/websites. Because > it was brought out, VIM also has plugins for syntax highlighting, > instant rendering, etc. > It was also suggested to use Markdown for release notes. > > On Fri, Jul 17, 2020 at 5:12 PM Matias N. <mat...@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. <mat...@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 <a...@starcat.io>