cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Upayavira ...@upaya.co.uk>
Subject Re: Automatically generated docs
Date Fri, 11 Mar 2005 09:58:36 GMT
Reinhard Poetz wrote:
> 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?

Yup. That's pretty much how I see it. Thanks for saving me the job of 
writing it myself!

Basically, I'm proposing we do the same with the generated docs as we do 
with the blocks.properties file, generate them at 'change' time, and 
commit the generated documents. When I rework the component, I will 
attempt to make it do its work so that it is easy to tell what to commit 
and what not.

Regards, Upayavira

Mime
View raw message