Hi Urs,
this looks great! As often, I can’t offer much more than applause and
some nitpicking…
On the ‘About LilyPond’ I’d rather write “GNU LilyPond is a music
notation program /strongly inspired by/ traditional craftsmanship”.
After all, the process of working with LilyPond doesn’t resemble
traditional craftsmanship at all…
The use of the word ‘domain’ in the About/LilyPond and /openLilyLib
seems quite technical considering IIUC the site is supposed to be read
also by people without a background in software development…
‘Get started/Install openLilyLib’ has an instance of [oll-core} that
seems unintentional.
s/documenation/documentation
… but generally, the texts seem very appropriate and useful :-)
Very best regards
Simon
On 20.02.20 22:44, Urs Liska wrote:
Hi all,
as a starting point for a - hopefully - comprehensive documentation
effort I have finally updated https://openlilylib.org with a completely
new website, which I'd like to have some feedback about and
contributions for.
There are several parts to that effort, most of which are essentially
not started yet.
* A general introduction website. This is basically complete and
should finally give a proper introduction about what OLL "is" and
how it can be made to work
* Independent sub-sites for each OLL package. These have not been
written at all, only the links to empty starting pages work without
404 errors.
* I've settled with MkDocs (https://www.mkdocs.org), which seems to
provide what I need, especially a suitable way to hook into and
extend to our needs.
* 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.
* There's a link to a contributor's guide, which is also essentially
empty, except for an entry page.
What I have so far is an infrastructure for textual, Markdown-authored
manuals, although I have already created a plugin for LilyPond syntax
highlighting using python-ly (
https://github.com/uliska/markdown-lilypond/).
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.
Best
Urs
