On Thu, Nov 11, 2021 at 5:33 PM Jean Abou Samra <[email protected]> wrote:
> > > The standard autodocumentation tools wouldn't help > much either. > > - The bulk of the work is extracting information from > LilyPond's internals. Take predicates. Their mapping > to names is maintained in the code, so we would have > to make the tool aware of our predicates. > > - Our concepts of "grobs", "interfaces", "engravers", > "contexts", etc. are not understood by tools that > work in terms of "classes", "methods", "members" > and such. > > >From what I understand, the core of the documented items is in the C++ code. But if you autogenerate the documentation from that code, you would have a set of classes and functions in a different "language" than the one used in the current documentation. Then you have to extract all these infos and translate them to your conventions (grobs, interfaces, engravers etc.). This is why I suggested a "static" wrapper, which should not be difficult to maintain because, even if introduces a redundancy with the set of names, this set will not be expanded or changed in the future. I mean: TimeSignature won't be replaced with something else in the future, and (I suppose) it's unlikely that new concepts will be added. Then a "TimeSignature_wrap", with links to the respective comments in the C++ code, won't be changed. So: what do you mean with "their mapping is maintained in the code"? From what I see, once the mapping is statically done it should not be maintained. Anyway, I could be wrong and in any case I'll show you some practical examples of what I have in mind in the next days. Best, P > - All styles (like CSS stylesheets) are tailored for > texi2html and shared across all the documentation. > The tool in question would necessarily have to generate > Texinfo input. Doxygen and GTK-doc can't do that > (Sphinx can). > > Overall, LilyPond's code base is quite special in > a number of regards and existing autodocumentation > tools are not suited well to it. > > While I wouldn't be against moving to a different > documentation tool (with a marked preference for Sphinx), > we would have to do it for all of the documentation at > once, it would be a big change, and it would not really > reduce the amount of scripting required to generate > the Internals (which is not all that much of a hassle > in the end). > > Best regards, > Jean > >
