Version documentation is quite useful, specially for such a dynamic project > as NuttX. I'm not sure it would require to have everything in a single > repo, since it is not really necessary to tie every single code commit to a > doc commit. I think a doc for master, updated as the code evolves, while > having doc tagged with the same version numbers as the codebase, could be > already enough and simple enough.
That works– what I was trying to say was that the docs need to have the same version as the release numbers, so you can know you're reading accurate docs for that version. As long as we have process to keep them in sync, we're good. Having separate repos will also simplify dealing with doc PRs vs code PRs, > can have different maintainers, requirements, CI system, etc. (imagine > having a doc update triggering a full CI rebuild). > To me, it's a preference– with most CI systems you can set it to watch certain directories or types of files. Again, I would encourage you to think in a scenario where you have a > specific repo holding all documentation which describes how to use and work > with NuttX, starting from simple "quickstart", to advanced technical > information and even an API reference. Agreed. This is also my vision. > In that case, READMEs throughout the repo would not need to have a lot of > the information that today exists there, sprinkled in all of the READMEs. > For that reason, I don't think it is worth it using something richer than > Markdown for READMEs. > As long as we can mix Markdown and RST (or whatever we use for the richer documentation) then Markdown is ok with me. Where this would come in handy is something like the Supported Boards tree you've been describing. In Zephyr each board doc is a seamless part of the main docs. > Anyways, if it comes down to "use the same for everything, or leave it as > is" I would indeed vote for the first option Likewise. But if we use Sphinx we can mix Markdown and RST. However, Zephyr went with "everything the same" and just uses RST (Zephyr supported boards <https://docs.zephyrproject.org/latest/boards/index.html>; example board Nitrogen <https://docs.zephyrproject.org/latest/boards/arm/96b_nitrogen/doc/index.html>; example board nitrogen RST on github <https://github.com/zephyrproject-rtos/zephyr/blob/master/boards/arm/96b_nitrogen/doc/index.rst> ). -adam -- Adam Feuer <a...@starcat.io>
