Thanks Matias. Following Matias' proposal, here's a separate repo with just one page of the HTML docs partially converted:
https://github.com/adamfeuer/nuttx-docs The files here could also be copied into a directory in the nuttx source tree too, for instance under Documentation/sphinx-docs instead of living in a separate repo. You can see the docs rendered using the Sphinx Read the Docs Theme here: https://nuttx-docs.readthedocs.io I converted this with pandoc and some Vim macros– the supported boards table didn't get done right, so needs more work, and pandoc also messed up the internal links, so they need to be fixed. But this gives the idea about how the docs would look, at least. I'll add an example Markdown file here so we can look at how the mixed ReStructuredText / Markdown stuff looks together. -adam On Mon, Jul 20, 2020 at 2:26 AM Xiang Xiao <xiaoxiang781...@gmail.com> wrote: > 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 > > -- Adam Feuer <a...@starcat.io>
