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
