Bertrand Delacretaz wrote: > On Wed, Apr 1, 2009 at 8:58 AM, Carsten Ziegeler <[email protected]> wrote: > >> ... I'm not happy about including these things into the bundle. And I'm also >> not sure about having the docs in svn - but that's the old discussion >> about the better way of editing/maintaining the docs (svn vs. wiki etc.)... > > I think it would be very hard to keep things in sync between svn and > the wiki, once our bundles have independent release cycles. Call me > pessimistic but I don't think we'd manage. > > We can still use the wiki for general/overview docs (though that might > also be an "overview" bundle with just docs), and use the bundle-based > docs for the reference stuff. > >> ...Let's keep the stuff separate, we have a bundle jar, a source jar, a >> javadoc jar and maybe the docs jar. If someone needs all of these as a >> single archive it's easy to create one out of those artifacts.... > > That might work, and what do you think about generating the docs of a > particular Sling instance based on which bundles are installed? I > think that's the key point in my proposal, exactly where the docs come > from is more an implementation detail. > > With docs in a separate bundle, the docs service would need to list > bundles for which there's no corresponding "docs" bundle installed, > that shouldn't be too hard to do based on conventions on bundle > symbolic names (i.e. foo.slingdocs is the docs of the foo bundle). And > with an OBR (http://www.osgi.org/Repository/HomePage), docs bundles > could be downloaded semi-automatically. > > -Bertrand (and I'm very serious BTW, as usual ;-) Yes, I know.... :)
Ok, I think this can be handled easily: if the docs are in a separate artifact which is in a Maven repository, we can write a simple module which downloads and extracts all available docs bundle for the installed bundles. This could be done at runtime of the system - or we could write a maven plugin which just aggregates the javadocs for all included bundles. Keeping these things separate (code from docs) seems to me the better way to handle it; it's easier to aggregate stuff later on then to separate it. Carsten -- Carsten Ziegeler [email protected]
