Re: Status new Cocoon documentation
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?
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
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)
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
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.
- o -
For SCD I propose 1) so that SCD use the style and the navigation and for
Javadocs option 4)
WDY(O)T?
--
Reinhard Pötz Independant Consultant, Trainer (IT)-Coach
{Software Engineering, Open Source, Web Applications, Apache Cocoon}
web(log): http://www.poetz.cc
Re: Status new Cocoon documentation
David Crossley wrote: Reinhard Poetz wrote: Last week Upayavira and I spent some time to overhaul the structure of the two document repositories: - http://brutus.apache.org/docs/build/cocoon-doco-2-2/ - http://brutus.apache.org/docs/build/cocoon-doco-global/ We think that it covers all Cocoon relevant topics and is a good starting point to evaluate and move over all existing documents. As this will be a lot of work we need all the help we can get. Check out http://wiki.apache.org/cocoon/CocoonDocumentationSystemHowTo what you have to do actually. Apart from helping to move over docs into our new repositories, my next steps are to: 1. finish my work on forrest repositories (comment and metadata part) 2. make the two repositories (currently they are in http://svn.a.o/r/a(cocoon/whiteboard/doc-repos) the official doc repositories of Cocoon 2.2 and move them over to the appropriate places (I will call for a vote on this very soon) 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 How is it done now on Brutus? Isn't there a hook within Forrest to call Cocoon's build docs before building the site? That way, the automatic enhancement of the docs is always done on top of whatever is in the new repository, much as it is now. Have I missed something? Regards, Upayavira
Re: Status new Cocoon documentation
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
Re: Status new Cocoon documentation
Upayavira 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 How is it done now on Brutus? Isn't there a hook within Forrest to call Cocoon's build docs before building the site? That way, the automatic enhancement of the docs is always done on top of whatever is in the new repository, much as it is now. Have I missed something? That is correct - the forrestbot is doing what you say. At the moment i have a wrapper shell script that first does an svn update of Cocoon's java sources and core blocks, calls 'build docs', then the forrestbot takes over. That works but is cumbersome. Evidently forrestbot itself could call Cocoon's 'docs' ant target prior to starting. I am working during spare time to get that happening, as there are various glitches. The trouble that i have with the new documentation proposal is that docs sources are moving to another part of the repository, so how will 'build docs' be able to access them? I suppose that assumed default relative pathnames with lots of dot-dots. --David
Re: Status new Cocoon documentation
David Crossley wrote: Upayavira 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 How is it done now on Brutus? Isn't there a hook within Forrest to call Cocoon's build docs before building the site? That way, the automatic enhancement of the docs is always done on top of whatever is in the new repository, much as it is now. Have I missed something? That is correct - the forrestbot is doing what you say. At the moment i have a wrapper shell script that first does an svn update of Cocoon's java sources and core blocks, calls 'build docs', then the forrestbot takes over. That works but is cumbersome. Evidently forrestbot itself could call Cocoon's 'docs' ant target prior to starting. I am working during spare time to get that happening, as there are various glitches. The trouble that i have with the new documentation proposal is that docs sources are moving to another part of the repository, so how will 'build docs' be able to access them? I suppose that assumed default relative pathnames with lots of dot-dots. A different part of the repository? Well, they'll according to the proposal, they'll soon be moving back into where they have always been in trunk (src/documentation). So I don't see what the problem is there. Maybe you're referring to block documentation (for which there actually isn't any at the moment). This I guess would need to be dot-dots back to a checkout of the blocks repository or repositories - or more likely each block would have its own forrestbot setup (assuming that isn't too complex). Does that make more sense? Regards, Upayavira
Re: Status new Cocoon documentation
Upayavira wrote:
David Crossley wrote:
Upayavira 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
How is it done now on Brutus? Isn't there a hook within Forrest to
call Cocoon's build docs before building the site? That way, the
automatic enhancement of the docs is always done on top of whatever
is in the new repository, much as it is now.
Have I missed something?
That is correct - the forrestbot is doing what you say.
At the moment i have a wrapper shell script that first does an svn update
of Cocoon's java sources and core blocks, calls 'build docs', then the
forrestbot takes over. That works but is cumbersome.
Evidently forrestbot itself could call Cocoon's 'docs' ant target prior
to starting. I am working during spare time to get that happening,
as there are various glitches.
The trouble that i have with the new documentation proposal is that
docs sources are moving to another part of the repository, so how
will 'build docs' be able to access them? I suppose that assumed default
relative pathnames with lots of dot-dots.
A different part of the repository? Well, they'll according to the
proposal, they'll soon be moving back into where they have always been
in trunk (src/documentation). So I don't see what the problem is there.
I think so too. After understanding now how it works, there shouldn't be any
problems as we can use the same behaviour in the future.
Maybe you're referring to block documentation (for which there actually
isn't any at the moment). This I guess would need to be dot-dots back to
a checkout of the blocks repository or repositories - or more likely
each block would have its own forrestbot setup (assuming that isn't too
complex).
If a block has its own docs repository (I will setup one for the Portal block)
it should also be built by forrestbot.
David, do you have any further questions about auto-docs?
--
Reinhard Pötz Independant Consultant, Trainer (IT)-Coach
{Software Engineering, Open Source, Web Applications, Apache Cocoon}
web(log): http://www.poetz.cc
Re: Status new Cocoon documentation
Reinhard Poetz wrote: Upayavira wrote: David Crossley wrote: [snip] The trouble that i have with the new documentation proposal is that docs sources are moving to another part of the repository, so how will 'build docs' be able to access them? I suppose that assumed default relative pathnames with lots of dot-dots. A different part of the repository? Well, they'll according to the proposal, they'll soon be moving back into where they have always been in trunk (src/documentation). So I don't see what the problem is there. I think so too. After understanding now how it works, there shouldn't be any problems as we can use the same behaviour in the future. Great ... it turned into a non-issue. Maybe you're referring to block documentation (for which there actually isn't any at the moment). This I guess would need to be dot-dots back to a checkout of the blocks repository or repositories - or more likely each block would have its own forrestbot setup (assuming that isn't too complex). Not complex. If a block has its own docs repository (I will setup one for the Portal block) it should also be built by forrestbot. Let me know when you are ready and i will add it to brutus. David, do you have any further questions about auto-docs? Not at this stage. --David
Re: Status new Cocoon documentation
Reinhard Poetz wrote:
Last week Upayavira and I spent some time to overhaul the structure of the
two
document repositories:
- http://brutus.apache.org/docs/build/cocoon-doco-2-2/
- http://brutus.apache.org/docs/build/cocoon-doco-global/
We think that it covers all Cocoon relevant topics and is a good starting
point
to evaluate and move over all existing documents. As this will be a lot of
work
we need all the help we can get.
Check out http://wiki.apache.org/cocoon/CocoonDocumentationSystemHowTo what
you
have to do actually.
Apart from helping to move over docs into our new repositories, my next
steps
are to:
1. finish my work on forrest repositories (comment and metadata part)
2. make the two repositories (currently they are in
http://svn.a.o/r/a(cocoon/whiteboard/doc-repos) the official doc
repositories
of Cocoon 2.2 and move them over to the appropriate places (I will call
for a
vote on this very soon)
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
--David
3. call for help on [EMAIL PROTECTED] (writing docs)
4. work the online editor for docs (Jeremy, thanks again for your work on
how
to access SVN using webdav!!!)
--
Reinhard P?tz Independant Consultant, Trainer (IT)-Coach
{Software Engineering, Open Source, Web Applications, Apache Cocoon}
web(log): http://www.poetz.cc
