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 <
[email protected]> 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. <[email protected]> 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. <[email protected]>:
> > >
> > > >
> > > > > 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 <[email protected]>
