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