[openlilylib] documentation browser and generator (start)

[Urs Liska]

Hi all,

despite the fact that I absolutely can't afford it I have started 
writing some stuff for a new openlilylib.
As it turned out  we won't have a script to (only) generate 
documentation for the library but rather a tool that can

- generate HTML documentation for the library
- browse the library by snippet name, category, tag, author (and 
possibly more options in the future)
- display documentation for a selected snippet (built on-the-fly from 
the actual snippet)

That's what I started to implement, you can have an impression from the 
screenshot:
http://openlilylib.org/screenshots/oll-doc-screenshot.png

In addition one will be able to use the tool to _edit_ snippet metadata, 
e.g. by selecting tags from existing ones etc. and having instant 
feedback from the generated documentation page.

As this implies that the whole documentation for openlilylib will be 
built from the snippets themselves there will be some restrictions to 
the coding conventions. These will have to be updated during the 
reorganization. For example any free-form comments will be discarded, so 
everything has to go into explicit fields. On the other hand I find it 
nice that you can now see how for example the "snippet-description" will 
turn out in the documentation page, so this will be an incentive to 
write better headers for new and existing snippets.

There is still a long way to go, but I think we have a great start. And 
I would like to ask anybody who is willing and able for assistance. If 
more people help working on this we will reach something beautiful 
earlier ;-)
The program itself is a PyQt application (like Frescobaldi), but there 
is significant headroom for help in the HTML/CSS part and for general 
discussion.
One particular topic I would appreciate someone to look into is 
integrating the ly-music module from Frescobaldi, initially at least to 
provide formatted LilyPond listings in the tool and in the generated 
HTML docs.

Anybody who wants to have a look is encouraged to (git) checkout the 
reorganization or the doc-script branch from the openlilylib repo.

Best
Urs