Hi Betrand, Bertrand Delacretaz schrieb: > Hi, > > I thought about this a bit more, and reading people's comments I > realize that what I really want is to have per-bundle versioned docs, > so that people can find up-to-date docs for their own set of bundles. > > Fortunately there's the web ;-) > > So simply having strict conventions for publishing our docs on the > website would do, we don't need to ship the docs. > > So here's a revised proposal, using large parts of Felix's: > >> Each Maven module is configured to generate JavaDoc of its exported packages > > Ok, and the javadocs are published on the website when the module is > released, under a path that can be deduced from the bundle's symbolic > name and version number. And with a CSS that matches the website's. > > For example, the javadocs for V1.4.2 of the org.apache.sling.foo > bundle are found under > > /bundles/org.apache.sling.foo/1.4.2/docs
This would be .../javadoc, right ? +1 > > on our website. > >> * Each Maven module may have more module-specific documentation which >> is not included on the site. > > Ok, and such docs are published like the javadocs, under a path like > > /bundles/org.apache.sling.foo/1.4.2/javadocs This would be .../docs, right ? +1 > >> * For general documentation (like the 15-minutes intro or architecture docs, >> etc.) >> we keep the Confluence based site > > Ok to start with, but if the in-module docs thing works well we might > later move a large part of this to an "overview" module which has just > docs. Maybe yes. We already have the site project. So this could just go there... OTOH, I still like the wiki editing and esp. the ease of publishing.... Using an build tool, this could of course be automated, too. > >> * Create a new maven module, which contains the site a copy >> of the site, which may be deployed into Sling as needed > > Maybe...or maybe just add links in the OSGi console, to each bundle's > docs and javadocs, based on the above path conventions. We can already do this (and actually do), since a bundle may have the Bundle-DocURL manifest header, which we can configure appropriately. Regards Felix > > -Bertrand >
