Btw, first I thought this is an aprils fool joke :) Carsten
Bertrand Delacretaz wrote: > Hi, > > Considering we're aiming for individual release cycles for our bundles > (or groups of bundles), I think the only sane way for docs to be in > sync with the bundles is to have those docs *inside* the bundles. And > maintain them alongside the source code. > > Bundle jars could store docs (in simple unstyled HTML or APT format) > under /SLING-INF/docs for example, and a service would pick them up > and dynamically assemble documentation pages for the current > combination of bundles that is installed, available under > /system/sling/docs. > > Doc paths from that page should be normalized to contain the bundle > symbolic ID and version, for example > > /system/sling/docs/bundles/org.apache.sling.servlets.get/2.0.2/ > > And the same for javadocs, /system/sling/docs/javadocs/... > > This will make our bundles a bit larger (thought we don't have tons of > docs ATM ;-), to get a feel I tried putting the javadocs and the > current website pages that relate to the > org.apache.sling.servlets.post bundle in a jar, resulting compressed > size is 77kBytes, that's not too bad, though that bundle jar is > currently 62kBytes, so including docs would more than double it. But > the convenience trumps the size increase, IMO. And providing a tool, > or build profile, that strips the docs from bundles is not hard. > > We might need some javadocs customization to create links to > interfaces that are in different bundles, and I'm not sure how to > handle the "2.0.2" version number in the above path for this. Maybe > provide a "current" alias to this for such links, that redirects to > the actual version being installed. > > The reference docs part of the website can then be generated by > running Sling with the current set of bundles, and spidering the docs > starting at /system/sling/docs. > > We can discuss the details of course, but WDYT about the general idea? > > -Bertrand > -- Carsten Ziegeler [email protected]
