On Tue, Apr 25, 2023 at 1:10 PM Tomek CEDRO <to...@cedro.info> wrote:
> On Tue, Apr 25, 2023 at 5:47 PM Brennan Ashton wrote: > > On Tue, Apr 25, 2023, 3:18 PM Gregory Nutt wrote: > > > My experience with using Deoxygen on large, projects has been > > > disastrous. People don't always maintain the tags to the documentation > > > was wrong and so the auto-generated documentation was not > > > trust-worthy. So you always end up looking at the code anyway. There > > > is nothing in the auto-generated code that is not in the the files so > > > there is no real value added (there would be if you could trust it). > > > > > > Also, minor errors in the tags cause a lot of CI failures. A couple > per > > > week. > > > > > > I suppose if documentation tags were added to all files and were all of > > > the highest quality, it would be a good thing. That that would be an > > > enormous job and ongoing maintained of the documentation tags would be > a > > > problem: Most people won't change them or put in useless, low value > > > tags. Much like PR comments. Or comments and documentation in general. > > > > > > If we could do it right, then +1 with a significant commitment of time > > > and effort. If we would do only a half-assed job, then -1. > > > > I _very_ much agree. I have very rarely found doxygen to be useful and > > usually just results in unhelpful boilerplate to make the tool happy and > > generates some html that no one will ever look at again. It is usually > > much better when someone spends the time to actually document the > > interfaces and the why behind them (like man pages) we already have a > > section in the docs for interfaces and it would be great as people extend > > and adapt them to continue keeping these up to date. > > Okay, Doxygen is the past.. currently Sphinx is the way to go, no > doubts, just an (not really convenient) example to keep doc in sync > with src and that can be quite PITA :-) > > > After some consideration a "safer" approach may be more desirable for now: > > 1. Migrate all documentation to a separate Documentation/ as it is > currently done, so we do not lose any content from > MediaWiki/README/CWIKI, we can add additional content that we need, > the documentation form is shaped to a satisfactory state, automation > is verified, nice references, tables of contents, sections, etc. > People will have solid documentation all the time and we cause no mess > and we can see how the work on doc goes in reality :-) Suggestion: The "separate" Documentation could be simply an "Unfinished" or "WorkInProgress" subdirectory inside Documentation. Just dump everything in there as quickly as possible and then gradually fixup and move sections to the right places. And then this: 2. When we have a well shaped "separate" documentation then it may be > the time to consider merging it with the source code, but not before, > if desired at all? doesn't require moving things from some other system into git. It will just become a rename within the repo. What do you think? I like the idea of keeping documentation in sync with the code(as much as possible given our volunteer-based project). The biggest pro for keeping doc within src is to stay in sync, maybe > to also have self documented source code. But there are also dangers > here, like messing up the whole unfinished doc and the source code!! > It would be wise to list all pros and cons and then after some time > make some decisions but not necessarily right now.. :-) At the very least, documentation will be included in our release artifacts, so people will have docs "offline" when they download releases. I think that's a good thing. Pros: > 1. It would be more coherent to keep doc inside src files and this > will result in better doc-in-sync-with-src. > 2. Source code will have documentation "inside". > 3. Sphinx has a better syntax than Doxygen so less ci / format / tag > errors may occur. > 4. Working examples are available as reference point > (https://github.com/kivy/kivy/tree/master/doc, > https://github.com/kivy/kivy/blob/master/kivy/config.py). > > > Cons: > 2. It can (and probably will) mess up current doc _and_ src!! > 2. Separation of documentation from the source code will enable easy > switch to other documentation system rather than rewrite of all source > code. > 3. This is even more work than migrating docs from wiki. > 4. This will make source files bigger (any impact on > (pre)process/build time or something?). > 5. The "separate" documentation is already out there just needs > reformatting (wiki -> rst). > > > > Additionally from this discussion I have opened two tickets from this > > thread. > > > > * Generate and publish the PDF alongside the html docs > > https://github.com/apache/nuttx/issues/9095 > > * A tracking ticket to unify more of the docs. > > https://github.com/apache/nuttx/issues/9094 > > > > I will start in on both once I return from holiday and have time in front > > of a real computer again. > > I am in, already subscribed! Full work power should arise around > July.. I will send some testing PR in the meantime. Thanks!! :-) Regarding the CWIKI, suppose we want to document something in particular. The CWIKI can be a good place for several people to put it together with realtime collaboration without having to deal with GitHub PRs and whatever, and when it gets close to ready, it can be migrated into Documentation. This is what we've been doing with the Release Notes and it seems to work well. Cheers Nathan
