Thanks Xiang. Does anyone else have feedback or improvement ideas?
cheers adam On Sat, Aug 1, 2020 at 1:28 AM Xiang Xiao <xiaoxiang781...@gmail.com> wrote: > 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 > > -- Adam Feuer <a...@starcat.io>
