Reinhard Poetz wrote: > David Crossley wrote: > > >Here is one thing that i cannot grasp yet: > >How will the automatically generated "Sitemap Component Documentation" > >(i.e. the old /userdocs/) fit in with these static repositories? > >Currently we need to run 'build docs' to prepare them, then do 'forrest'. > >http://cocoon.apache.org/2.1/plan/review-sitemap-docs.html > > For me it's very important that whatever the solution is, it must be usable > with forrestbot because otherwise we would lose the automatic deployment. > > IIUC you build the sitemap-component-docs (SCD) on your local machine and > commit them into the SVN, don't you?
I am not sure what you are asking. The 'build docs' generates some extra xml source for forrest to consume. It copies the xml sources to a temp directory, generates the installing/jars.xml, re-writes the /userdocs/*.xml by reading the original manually maintained content and merging it with stuff gathered from the relevant *.java source. Nothing is committed to svn there. Then forrest is called to generate the html/pdf which is then manually committed to cocoon-site svn. > You ask how this can be done with the static repositories. I see following > alternatives: > > 1) do it similarly as it is done now. Have an Ant target that generates the > SCD file and it has to be committed into SVN whenever we think that it has > to be updated. > > pro: simple > con: danger of out-dated docs Sorry, i don't understand Option 1. What gets committed to SVN? > 2) automatic process that generates the SCD and commits them into our SVN > > pro: docs are up-to-date > con: IIUC this isn't allowed because of Apache policies (not automatic > commits) IIUC policies can be changed if all bases are covered. > 3) tweak Forrest so that it can call Ant targets (checkout sources, > generate SCD) > > pro: solution within Forrest > con: a lot of work, upgrade to the unstable Forrest 0.7 I have actually considered that that is probably the best. Personally i don't have the wherewithall to do that at the moment. > 4) build and deploy the SCD without Forrest and put the SCD docs into > http://cocoon.apache.org/2.2/sitemap-components/ and > > If the docs are build at your local machine this could be achieved by an > Ant target that runs forrest, a sitemap-components-generation-target and > the javadocs-target. > > pro: to Forrest changes, SCD are up-to-date > con: The disadvantage of this solution is that those generated docs don't > use the general skin and are not within the menu structure. That's no > problem for the javadocs but for the sitemap components docs. That sounds like just as much work as the other solutions > - o - > > For SCD I propose 1) so that SCD use the style and the navigation and for > Javadocs option 4) > > WDY(O)T? I would like to hear. --David
