strong -1 - This makes sphinx cross-references between nuttx pages and nuttx-apps pages impossible or difficult. Cross-reference is on of the main advantages of sphinx, why give it up.
- Using simple `grep` to search for information will be more difficult. The knowledge base will be divided into two separate repositories. - Maintaining two docs and integrating them in one place on the website is more difficult. The resources needed for this can be much better used in the project: https://github.com/apache/nuttx/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22Area%3A%20Documentation%22 - I don't see what problem this is supposed to solve. If the PR on the nuttx-apps isn't merged yet, then we don't merge the doc PR on the nuttx side. That's all :) pt., 4 lip 2025 o 18:19 Tiago Medicci Serrano <tiago.medi...@gmail.com> napisał(a): > Hi, > > I totally agree with Tomek: we need to work on a prototype for it. > > Best regards, > Tiago > > Em sex., 4 de jul. de 2025 às 09:19, Tomek CEDRO <to...@cedro.info> > escreveu: > > > Hmm, from user perspective this may help bundling apps documentation > > directly with apps code changes in the same nuttx-apps repo, > > users/developers complain about that, especially newcomers. On the > > other hand this may introduce some incoherence and additional > > scenarios. > > > > Because apps documentation is located in Documentation/applications > > this should be possible to script on the nuttx-website repo and/or > > nuttx repo to build the complete documentation if the nuttx-apps is > > present. Not sure if/how the static cross-references would work in > > sphinx if the nuttx-apps is absent we would have to verify that, or > > just require both nuttx and nuttx-apps to be present in order to build > > the documentation. > > > > I think a working prototype should be tested before we vote in the change > > :-) > > > > Thanks :-) > > Tomek > > > > On Thu, Jul 3, 2025 at 9:17 PM Nathan Hartman <hartman.nat...@gmail.com> > > wrote: > > > > > > Hi all, > > > > > > Right now, Documentation is in the main nuttx repository [1]. > > > > > > However, some of the Documentation there pertains to the nuttx-apps > > > repository. One current example is PR #16665 in nuttx repo, which is > > > documenting the new Xedge example located in the nuttx-apps repo. > > > > > > I think it's a little bit messy to have documentation in nuttx repo for > > > things that belong in nuttx-apps repo. One disadvantage is that repos > can > > > get out-of-sync. Another disadvantage is that NuttX users are not > > required > > > to use nuttx-apps repo. They can supply their own. But, they will have > > > Documentation about things in nuttx-apps repo. That could be confusing > > > because they might see something in Documentation but will not be able > to > > > find it. > > > > > > I suggest to create a Documentation in nuttx-apps repo and move all > > > apps-related docs there. So nuttx/Documentation will only document > things > > > in the nuttx repo, and nuttx-apps/Documentation will only document > things > > > in the nuttx-apps repo. If we do this refactoring, it will mean that > the > > > website will need an update also, to pull docs from both sources > > > (nuttx/Documentation and nuttx-apps/Documentation). > > > > > > Thoughts? > > > > > > [1] https://github.com/apache/nuttx > > > > > > [2] https://github.com/apache/nuttx/pull/16665 > > > > > > [3] https://github.com/apache/nuttx-apps/pull/3120 > > > > > > Cheers, > > > Nathan > > > > > > > > -- > > CeDeROM, SQ7MHZ, http://www.tomek.cedro.info > > >
