Discuss API and module documentation system

[uliska]

(Followup for #53)

For a healthy evolution of openLilyLib we need a way to reliably auto-generate documentation. A first attempt has been made on the docscript branch, in the docgen directory, but probably this doesn't fit the new library structure.

There are two aspects to that: module and API documentation and usage examples

Module documentation

The current system of oll- prefixed \header fields is a good start to provide documentation of library files/units/modules as a whole. We should discuss and decide about an authoritative structure with mandatory, optional and custom fields and lay that down in a Contributor's Guide.

A documentation generating script should retrieve module information from that and also perform validity/plausibility checks. Failure should not result in stopping the generation but in some form of notification so people are directed at fixing things.

API documentation

We should discuss and decide upon a syntax to enter API documentation to LilyPond files. Processing of that should be done by creating a new Python module which aims at being independently usable, e.g. for providing syntax highlighting or auto-completion in editors.

It should be discussed whether this should be a new module or if it's suitable to add this to python-ly.

API documentation has to be integrated in the overall generated documentation.

Usage examples

All implemented functions in an openLilyLib library should be covered by usage examples (basically as is already standard). But it has to be discussed what is the best way this could complement the module documentation.

usage examples should be mandatory and should be used for automated testing. (See also https://github.com/openlilylib/openlilylib/pull/60).

[uliska]

Adding one more aspect:

Unit tests

As discussed in #86 the usage examples should be separated from and complemented by unit tests.