Re: Use Maven 2 for the generation of the Cocoon documentation
Bruno Dumon wrote:
OTOH, having the docs
split up between a lot of little maven-sites might lessen the overview.
Because of the nature of Daisy this shouldn't become a problem:
- we can have one navigation document which is a collection of all
block navigation docs
- we have Daisy books
- if that's not enough, we can refer to the same document from different
navigation docs
--
Reinhard Pötz Independent Consultant, Trainer (IT)-Coach
{Software Engineering, Open Source, Web Applications, Apache Cocoon}
web(log): http://www.poetz.cc
___
Telefonate ohne weitere Kosten vom PC zum PC: http://messenger.yahoo.de
Re: Use Maven 2 for the generation of the Cocoon documentation
Bruno Dumon wrote: On Mon, 2006-03-06 at 18:39 +0100, Reinhard Poetz wrote: hepabolu wrote: Finally, adding the proposed plugin can always be added later without loosing the effort of the current setup. ok, that's right. Anyway, I can't do it myself now but if somebody is interested, I can help. Maybe some of the Daisy gurus here can comment on the idea itself? It shouldn't be too hard. If it is just for publishing, you don't even need the Daisy client libraries, being able to do a HTTP request is enough. Actually, I should correct my previous statement the Forrest plugin uses the http API not the Java client API. No need for the Java API at this stage. I'm not sure what the difficulties are that Ross refers too in reusing the navigation documents. A basic plugin can probably be created in a day (by an experienced Java/XSLT person). Actually, my comment was misleading, sorry. The difficulties are not with Daisy itself, rather with the fact that we need(e) to maintain the existing directory structures of the documents and the Daisy nav system didn't work in the same way as the old nav system. With the 2.2 docs there is no legacy structure to maintain so it will be much easier. Ross
Re: Use Maven 2 for the generation of the Cocoon documentation
On Tue, 2006-03-07 at 09:06 +0100, Reinhard Poetz wrote: Bruno Dumon wrote: OTOH, having the docs split up between a lot of little maven-sites might lessen the overview. Because of the nature of Daisy this shouldn't become a problem: - we can have one navigation document which is a collection of all block navigation docs - we have Daisy books - if that's not enough, we can refer to the same document from different navigation docs Yes indeed, we can republish the same content in different ways. -- Bruno Dumon http://outerthought.org/ Outerthought - Open Source, Java XML Competence Support Center [EMAIL PROTECTED] [EMAIL PROTECTED]
Re: Use Maven 2 for the generation of the Cocoon documentation
Reinhard Poetz schrieb: As written in my mail Status of block development (http://marc.theaimsgroup.com/?l=xml-cocoon-devm=114165989221631w=2) I propose a change in the Cocoon documentation creation: We have put a lot of work into the Mavenization of the Cocoon build system. As you might know, Maven provides a site generation goal site:site. This makes is very simple to integrate a lot of reports (javadocs, jdepend, cobertura, svn activities, ...) and uses information available in pom.xml to produce docs. IMO the only missing part is the integration of our docs that are managed by Daisy. My idea is: - write a Maven plugin that can access Daisy - it is configured by the doc-id of a navigation documentent which is the root of the block documentation - the plugin uses the Daisy client API to access this navigation doc and generates docs out of it by crawling all references docs and resources. The result of this process is added to the generated site. First, does this proposal make sense from a technical point of view? Is anybody interested in working on this? I can help with the Maven part of starting a Maven plugin project a bit. [I've cc'ed the Daisy mailing list as there might be people who are interested in such a plugin too and may consider helping out on writing it.] I'm more than +1 for getting the reports Maven provides for us on our website. I'm not sure if we need a plugin for the daisy docs or if just linking from the maven generated site is enough. Whatever works best. Carsten -- Carsten Ziegeler - Open Source Group, SN AG http://www.s-und-n.de http://www.osoco.org/weblogs/rael/
Re: Use Maven 2 for the generation of the Cocoon documentation
Carsten Ziegeler wrote:
Reinhard Poetz schrieb:
As written in my mail Status of block development
(http://marc.theaimsgroup.com/?l=xml-cocoon-devm=114165989221631w=2) I propose
a change in the Cocoon documentation creation:
We have put a lot of work into the Mavenization of the Cocoon build system. As
you might know, Maven provides a site generation goal site:site. This makes is
very simple to integrate a lot of reports (javadocs, jdepend, cobertura, svn
activities, ...) and uses information available in pom.xml to produce docs.
IMO the only missing part is the integration of our docs that are managed by
Daisy. My idea is:
- write a Maven plugin that can access Daisy
- it is configured by the doc-id of a navigation documentent which is the
root of the block documentation
- the plugin uses the Daisy client API to access this navigation doc
and generates docs out of it by crawling all references docs and resources.
The result of this process is added to the generated site.
First, does this proposal make sense from a technical point of view?
Is anybody interested in working on this? I can help with the Maven part of
starting a Maven plugin project a bit.
[I've cc'ed the Daisy mailing list as there might be people who are interested
in such a plugin too and may consider helping out on writing it.]
I'm more than +1 for getting the reports Maven provides for us on our
website. I'm not
sure if we need a plugin for the daisy docs or if just linking from the
maven generated site is enough. Whatever works best.
I consider one block as a unit and the docs are part of this unit. I want to see
all pieces of information that belong to this unit, at *one* place and I don't
want to distribute it.
Additionally, if we use Maven as starting point for the doc generation we can
use Continuum to generate our site. And because of the nature of Maven 2 we can
geneate the site for one project or use a reactor build to create it all projects.
--
Reinhard Pötz Independent Consultant, Trainer (IT)-Coach
{Software Engineering, Open Source, Web Applications, Apache Cocoon}
web(log): http://www.poetz.cc
___
Telefonate ohne weitere Kosten vom PC zum PC: http://messenger.yahoo.de
Re: Use Maven 2 for the generation of the Cocoon documentation
Carsten Ziegeler said the following on 06-03-2006 17:49: I'm more than +1 for getting the reports Maven provides for us on our website. I'm not sure if we need a plugin for the daisy docs or if just linking from the maven generated site is enough. Whatever works best. Let's do this one step at a time and do Carsten's proposal first. I've been experimenting with exactly this just after the Cocoon Gettogether, but my Maven knowledge is not that good that I could get Maven to produce the reports. Linking to the official docs pulled from Daisy also allows more flexibility in separate updates (I suppose the maven part is more volatile than the docs) and in allowing a complete overhaul of either parts without affecting the other. Besides, the maven part serves a different purpose than the official docs (quick lookup vs more detailed study). So they might have a different layout/look feel. Finally, adding the proposed plugin can always be added later without loosing the effort of the current setup. So +1 for Carsten's proposal. Bye, Helma
Re: Use Maven 2 for the generation of the Cocoon documentation
hepabolu wrote:
Finally, adding the proposed plugin can always be added later without
loosing the effort of the current setup.
ok, that's right. Anyway, I can't do it myself now but if somebody is
interested, I can help. Maybe some of the Daisy gurus here can comment on the
idea itself?
--
Reinhard Pötz Independent Consultant, Trainer (IT)-Coach
{Software Engineering, Open Source, Web Applications, Apache Cocoon}
web(log): http://www.poetz.cc
___
Telefonate ohne weitere Kosten vom PC zum PC: http://messenger.yahoo.de
Re: Use Maven 2 for the generation of the Cocoon documentation
hepabolu schrieb: Carsten Ziegeler said the following on 06-03-2006 17:49: I'm more than +1 for getting the reports Maven provides for us on our website. I'm not sure if we need a plugin for the daisy docs or if just linking from the maven generated site is enough. Whatever works best. Let's do this one step at a time and do Carsten's proposal first. I've been experimenting with exactly this just after the Cocoon Gettogether, but my Maven knowledge is not that good that I could get Maven to produce the reports. Linking to the official docs pulled from Daisy also allows more flexibility in separate updates (I suppose the maven part is more volatile than the docs) and in allowing a complete overhaul of either parts without affecting the other. Besides, the maven part serves a different purpose than the official docs (quick lookup vs more detailed study). So they might have a different layout/look feel. Finally, adding the proposed plugin can always be added later without loosing the effort of the current setup. So +1 for Carsten's proposal. Hmm, actually, I didn't meant my comments to be a proposal :) But i have no problem seeing it this way :) I have no idea about the effort required to get a daisy maven plugin running. But I agree totally with Reinhard, that the docs for a block belong to the block (= unit). Carsten -- Carsten Ziegeler - Open Source Group, SN AG http://www.s-und-n.de http://www.osoco.org/weblogs/rael/
Re: Use Maven 2 for the generation of the Cocoon documentation
Reinhard Poetz wrote: As written in my mail Status of block development (http://marc.theaimsgroup.com/?l=xml-cocoon-devm=114165989221631w=2) I propose a change in the Cocoon documentation creation: We have put a lot of work into the Mavenization of the Cocoon build system. As you might know, Maven provides a site generation goal site:site. This makes is very simple to integrate a lot of reports (javadocs, jdepend, cobertura, svn activities, ...) and uses information available in pom.xml to produce docs. IMO the only missing part is the integration of our docs that are managed by Daisy. My idea is: - write a Maven plugin that can access Daisy - it is configured by the doc-id of a navigation documentent which is the root of the block documentation - the plugin uses the Daisy client API to access this navigation doc and generates docs out of it by crawling all references docs and resources. The result of this process is added to the generated site. First, does this proposal make sense from a technical point of view? Is anybody interested in working on this? I can help with the Maven part of starting a Maven plugin project a bit. I have no experience of Maven so can make no comment on that end of things. Reusing the Daisy navigation documents is not a trivial task, but it is certanly possible. What you describe is exactly what the Forrest plugin does. An alternative approach, and one that I am keen to follow if my own time allows (not right now). Is to create a Maven plugin for Forrest, thus we would use the two tools to produce what they are best at. However, as I said, I do not have the time to do this right now. So if someone wants to go the maven plugin route then go for it. Ross
Re: Use Maven 2 for the generation of the Cocoon documentation
On Mon, 2006-03-06 at 18:39 +0100, Reinhard Poetz wrote: hepabolu wrote: Finally, adding the proposed plugin can always be added later without loosing the effort of the current setup. ok, that's right. Anyway, I can't do it myself now but if somebody is interested, I can help. Maybe some of the Daisy gurus here can comment on the idea itself? It shouldn't be too hard. If it is just for publishing, you don't even need the Daisy client libraries, being able to do a HTTP request is enough. I'm not sure what the difficulties are that Ross refers too in reusing the navigation documents. A basic plugin can probably be created in a day (by an experienced Java/XSLT person). As for publishing the docs via Maven, I can understand the benefits to that, especially as each block will become less dependent on the core and might be versioned and released independently. OTOH, having the docs split up between a lot of little maven-sites might lessen the overview. In the short term, personally I'll focus on the actual content, as I think that's a more urgent issue. However, while writing docs, we should keep in mind to keep the docs related to a block grouped, focussed and independent from each other, so that we don't make this proposal harder to achieve. [only slightly related to this thread...] Something which I'll look in setting up soon is to allow to refer to javadoc using a javadoc: URL which gets translated to the actual javadoc location during publishing. To make it more block-oriented, the syntax will probably be something like javadoc:blockname:org/apache/ -- Bruno Dumon http://outerthought.org/ Outerthought - Open Source, Java XML Competence Support Center [EMAIL PROTECTED] [EMAIL PROTECTED]
