cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Reinhard Poetz <reinh...@apache.org>
Subject Automatically generated docs
Date Fri, 11 Mar 2005 07:06:34 GMT
Upayavira wrote:
> Reinhard Poetz wrote:
>> David Crossley wrote:
>>> Perhaps we should step back a bit and assess the situation. It seems
>>> a cumbersome process to double-handle all of the source docs, just to
>>> add some specially-generated docs. Would it help to put these special
>>> docs into a completely separate workspace?
>>
>>
>> I don't like this duplicaton process either. Well, as far as I 
>> understand, the reasons for this is that we want to style the docs 
>> using the common skin and not something different. The question is, do 
>> we really need the sitemap-component docs (some kind of API 
>> documentation) in this common style? I'd say no. They are similar to 
>> javadocs and nobody has ever complained about not having the tightly 
>> integrated in our website. (I don't want to say that I wouldn't like 
>> seeing all docs in the common style but it's not worth doing the huge 
>> amount of work to get it done.)
>>
>> Maybe  we can agree on this: Generated documentation is linked from 
>> our documenation but is not integrated in our common style:
>>
>> http://cocoon.apache.org/2.2/apidocs/
>> http://cocoon.apache.org/2.2/sitemap-components/
>> http://cocoon.apache.org/2.2/jars/
> 
> 
> If we are to do this, then we've at least to be consistent in linking to 
> the generated docs from the other documentation. i.e. the 
> SearchGenerator needs to have a prominent link directly to the section 
> describing the SearchGenerator.

Yesterday, Upayavira and I talked about this and we think we found a solution. 
Currently every document in Forrest consists of

document-name/
  ./content_en.xml or ./content_en.html
  ./meta.xml
  ./comments_en.xml

Additionally I introduced

  ./generated-before_en.xml
  ./generated-after_en.xml

These two documents can contain automatically generated stuff like that comming 
from the  the sitemap task. The aggregation process takes care that the 
automatically generated docs are added either before or after the actual content 
(content_en.xml).

Upayavira will adapt the existing task to support the flat document space. So 
the procedure in the future is, that whenever somebody is changing the Javadocs 
of a sitemap component, he has to run "build prepare-docs" too and this will 
update the generated-*.xml documents. He also has to check in these documents.

Those two additional steps shouldn't be too difficult, but they help us to build 
our docs out of the box using Forrest *without* some "black magic" (--> 
duplication of xdocs before they can be generated).
Additionally this makes writing an online-editor for the docs much easier as the 
separation between editable docs and automatically-generated docs is very clear.

A further idea: Forrest-bot could run this "build prepare-docs" target too and 
ensure this way that it always uses the latest docs.

Upayavira, is this in the sense of what we talked about yesterday? WDOT?

-- 
Reinhard Pötz           Independant Consultant, Trainer & (IT)-Coach 

{Software Engineering, Open Source, Web Applications, Apache Cocoon}

                                        web(log): http://www.poetz.cc
--------------------------------------------------------------------

Mime
View raw message