RE: new documentation
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. > 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
Re: new documentation
Thanks Xiang. Does anyone else have feedback or improvement ideas? cheers adam On Sat, Aug 1, 2020 at 1:28 AM Xiang Xiao 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. > > 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
Re: new documentation
Hi Adam, It is already getting a very good shape! This is a great improvement to NuttX! In the Supported Boards I think we could implement some table showing the supported status of each board, similar to this: https://wiki.postmarketos.org/wiki/Devices Some RTOSes claim to support some boards, but when you try to use it you discover only some basic features are supported. I think it is good for NuttX to make things clear from start. Just my 2 cents. BR, Alan On 8/1/20, Adam Feuer wrote: > Thanks Xiang. > > Does anyone else have feedback or improvement ideas? > > cheers > adam > > On Sat, Aug 1, 2020 at 1:28 AM Xiang Xiao > 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. >> > 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 >
