I looked at the content last week, but forget to send my feedback email, sorry. I definitely support the idea: the document is managed and released as the source code and collect all documents in one place. This step is very important to keep the consistent between the implementation and the documentation. It also encourage the contributor improve the document just like the code.
> -----Original Message----- > From: Matias N. <mat...@imap.cc> > Sent: Saturday, August 1, 2020 1:01 AM > To: dev@nuttx.apache.org > Subject: Re: new documentation > > Hi again, > I was wondering if you have checked the demo for the new documentation that > Brennan, Adam and me have put together. I'm really > looking forward to see this part of the official repo. If we can get some > validation on the this we can start building a PR to finish > migrating the HTMLs and link existing READMEs as a first step. We can > continue working on the content in iterations after that. > > Best, > Matias > > On Thu, Jul 23, 2020, at 11:22, Matias N. wrote: > > Hi, > > I started a new thread since the "Markdown READMEs" one was already too > > long and it is probably best to leave that one for the > Markdown conversion effort on its own. > > The last couple of days Brennan, Adam and me managed to build a > > working demo of the proposed documentation system. We used a separate > > repo since the CI jobs we're using (GitHub pages based) are not > > compatible with the main repo (I believe) and to build up something > > worth showing before opening a PR. You can see the result at: > > https://v01d.github.io/incubator-nuttx/docs/index.html > > > > Summary: > > 1. documentation is under doc/ directory although probably once the > > migration is done we would again use Documentation/ 2. on each push > > documentation is built using CI and sent to gh-pages branch. > code related jobs do not run for changes under doc/ to speed up PR reviewing. > > 3. most of the pages are stubs indicating its intended purpose, this > > is to be filled later 4. the two sections worth pointing out are > > "Introduction" and "C coding standard" under "Contributing". These are > the result of automatic conversion and then manual editing of NuttX.html > (done by Adam) and NuttXCCodingStandard.html (done by > me), respectively. The "details" part of "supported platforms" is not yet > fixed since we wanted to get feedback before continuing. The > coding standard should be completely converted. > > > > As for CI, Brennan mentioned that once integrated on the final repo we > > would probably have a job on nuttx repo that triggers the > website repo rebuild. Thus, it would be the website repo that does the build > and deploy itself. The nuttx repo can still do the build for > checking on PRs but it would not make the deploy. > > > > What do you think? It would be nice to receive confirmation that this is > > also pleasing by other users before continuing with the effort. > Also, in that case we can clean up these changes and start a PR on the main > repo and start trying the final CI approach. After that we > could finalize migration of the most important parts of the previous docs > (mainly the HTMLs). > > > > Best, > > Matias
