Hi,
I agree with the basic requirement and part of the approach. But, I
don't think we should include the per-bundle documentation in each bundle.
How about this:
* Each Maven module is configured to generate JavaDoc of its
exported packages
* Each Maven module may have more module-specific documentation
which is not included on the site.
* For general documentation (like the 15-minutes intro or
architecture docs, etc.) we keep the Confluence based site
* Deploy java docs and module docs to our site and better
integrate the site with the deployed docs (also use the same
CSS !)
* Create a new maven module, which contains the site a copy
of the site, which may be deployed into Sling as needed
WDYT ?
Regards
Felix
Bertrand Delacretaz schrieb:
> 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
>
