Can we keep the doc and nuttx in one git? The major of document is normally couple with the code. The separation make the synchronization between code and document more harder. Other similar project(e.g. Linux and Zephyr) use the same git manage both code and document: https://github.com/torvalds/linux/tree/master/Documentation https://github.com/zephyrproject-rtos/zephyr/tree/master/doc Other propose looks good to me. Maybe we can integrate wiki into the new document structure later.
Thanks Xiang > -----Original Message----- > From: Matias N. <mat...@imap.cc> > Sent: Monday, July 20, 2020 11:39 AM > To: dev@nuttx.apache.org > Subject: Re: Markdown READMEs? > > 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
