Am Freitag, den 21.02.2020, 18:52 -0800 schrieb ma...@masonhock.com: > On 02/20, Urs Liska wrote: > > What I really *want* to have but have no idea so far how to achieve > > is > > additional code/API documentation retrieved from the actual source > > files. There should be a tool to retrieve that from comments (or > > actual > > signatures?), resulting in either HTML or Markdown documentation > > that > > can be automatically integrated in the "manual-style" > > documentation. > > Do you want something similar [Sphinx][1] or [Doxygen][2]?
Yes, something similar, but IISC these tools (which I had of course taken notice of earlier) are limited to their set of languages. Parsing documentation comments or docstrings and producing API reference is what is still needed. One aspect that might be different from "traditional" API reference documentation in a case like openLilyLib (also like LaTeX packages) is that there are *end-user*-facing commands and *internal* commands. Internal commands (i.e. auxiliary functions) may or may not be interesting for users outside the package development, but probably the documentation should be kept separate in some way. For example by providing totally separate pages/trees or listing the end-user functionality first on a page, followed by the internal stuff. In addition I think the end-user functionality whould be documented on a package-based page while the internal API should be documented per source file. But I haven't fully thought through that topic yet. Craig Dabelstein did some research and suggested NaturalDocs ( https://www.naturaldocs.org/) which looks nice and suitably extensible/configurable for our purpose. I'm a little bit wary about the fact that it's a project with a single contributor, and I know what I'm talking about ... (also I *think* it would be good to have a Python-based tool because it might be easier to extend and to integrate with the other stuff. > Are the > source files in Scheme, Lilypond, or a combination of both? Of course both. The end-user interface is usually LilyPond, but the functionality is all LilyPond, Scheme-in-LilyPond, and Scheme-in-Scheme-files. Urs > > [1]: https://en.wikipedia.org/wiki/Sphinx_(documentation_generator) > > [2]: https://en.wikipedia.org/wiki/Doxygen
