search

openlilylib / oll-core

Library Infrastructure for LilyPond add-ons
17 stars 13 forks source link

Which targets are needed? #21

Open uliska opened 7 years ago

uliska commented 7 years ago

We need to decide what target formats the documentation should eventually address.

How can we make the documentation available to, say, Frescobaldi, both for a documentation browser, maybe editor tooltip and code completion? Maybe that's more an issue of the intermediate representation to draw from.

Blocks #26

Cecca commented 7 years ago

Some thoughts on the sources/targets listed above

  • Individual package's documentation vs. full openLilyLib

I think that the basic documentation generation tool should be targeted at individual packages, since openLilyLib will eventually turn into a curated collection of related packages, as far as I understood. Possibly, the basic mechanism of extracting documentation for lilypond files could be decoupled to openLilyLib: this way a user can document his own custom files for reference without the need to turn them into full-featured openLilyLib packages.

  • Set of HTML pages

This might be the default output format. Anyway, if we go for an intermediate representation we can have several output formats, as you are already suggesting. The intermediate representation could also enable a tighter integration with Frescobaldi, but I'm not familiar with that codebase, so I have no idea of what are the possibilities.

  • Interactive web application (Single page with live update of displayed content)?

I don't see the benefits of a single page web application with respect to a set of static HTML pages. Anyway, having an intermediate representation would enable also to have such an application.

uliska commented 7 years ago

I think that the basic documentation generation tool should be targeted at individual packages, since openLilyLib will eventually turn into a curated collection of related packages, as far as I understood.

Yes, that's right. One should also consider the option that a package maintainer wants to display his package's documentation on his own website.

So what we need is a single-package target, but keeping in mind that there will be a complete openLilyLib documentation somewhere that needs to stitch all the packages together.