Re: openLilyLib website

[Urs Liska]

Am Freitag, den 21.02.2020, 18:52 -0800 schrieb address@hidden:
> 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