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