Re: openLilyLib website

[Noeck]

Dear Urs,

it’s great that you found time for that. It looks nice and I think
MkDocs is a good choice (would have been my first choice, too).

While speaking about documentation, I very much like this approach:
https://www.divio.com/blog/documentation/

Some nitpicks from me:

- Should everyone see the "Edit this page" pencils?
   - Those links are broken for me
- If you descend into a package documentation, "Home" will not bring you
to openlilylib.org but to the page of the package. While that is
probably a consequence of your fourth bullet point, I find it confusing.
- Do you like the brown color?

>  * Each sub-site is maintained in a separate Git repository and
>    included as a Git submodule, so it should be straightforward to
>    manage independent authoring of the documentation by the respective
>    package maintainers.

While this theoretically makes sense to separate the packages'
documentation, I would run from git submodule. But perhaps your use case
is easier than where my experience comes from and you can still change
that decision later in case it makes things easier.

> 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?),

What do you mean by signatures?
IMHO, this makes sense for "reference-type" documentation in addition to
other parts of the documentation (cf. link at the top).

Cheers,
Joram