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
