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 docs, and sphinx can bridge the gap a little > anyway allowing embedding of markdown in its pages.
I proposed separate formats because I believe RST has the advantages I mentioned, however as other members expressed concerns about readability of README files, I think Markdown is more suitable since it does not require any "tag" to achieve most of its formatting. > 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. As I'm not an official maintainer I was unsure if calling a vote myself was appropriate. For that reason my last email was mostly to not loose track of this discussion and summarize to what I understood was discussed so far. > 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 README, which I think is the most "complex" README on the repo. I can open a PR for that. Best, Matias > > --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 >
