+1
Maintaining code coherency (including docs) is YUUGely more difficult
when separate repos are involved.
If the main reason for creating a second repo is to more cleanly have
two doc directories maybe Markdown isn't the answer you want anyway.
If the focus on pretty print is to use RST then "compile" READMEs from
the RST forms. Markdown doesn't really add much to a doc, IMHO, so
generating a README.txt from a RST based source would seem to be optimal.
Hell, Github may even take a PR for that feature.
Thanks,
Bill
On 7/20/2020 2:26 AM, Xiang Xiao 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
