Integrating auto-generated docs

[Reinhard Poetz <re...@apache.org>]

Some of us started with generating docs out of Java sources (sitemap 
components). I have to admit that I have no experience with this process but I 
would like to integrate these reference docs into the new documentation. The 
problem is, how can I configure Forrest to use an unknown number of docs and 
generate the menu *automatically*:

+-+ new documentation
   +-- getting started
   +-- tutorial
   +-+ reference docs
     +-+ generators
       +-- File Generator
       +-- JXTemplateGenerator
       +-- ...
     +-- transformers
     +-- ...

The only way I can think of is a hack using XML entities in site.xml and 
auto-generating the content of files, that these entities are pointing to. Or is 
there some better ("official supported") way of doing this?

-- 
Reinhard

Re: Integrating auto-generated docs

[Reinhard Poetz <re...@apache.org>]

David Crossley wrote:
> Reinhard Poetz wrote:
> 
>>Some of us started with generating docs out of Java sources (sitemap 
>>components). I have to admit that I have no experience with this process 
>>but I would like to integrate these reference docs into the new 
>>documentation.
> 
> 
> There is a rough explanation at
> http://cocoon.apache.org/2.1/plan/review-sitemap-docs.html
> 
> What you refer to as "reference docs" below, are what you see now
> on the website at /userdocs/$component/
> 
> 
>>The problem is, how can I configure Forrest to use an 
>>unknown number of docs and generate the menu *automatically*:
> 
> 
> The Cocoon SitemapTask that generates those reference docs already
> generates the book.xml files, which is the way Cocoon's forrest
> uses to generate the navigation panels. Using book.xml is an old way
> but it still works fine.
> 
> Anyway, my point is, that this is already being automatically generated.

ok. have to get familiar with combining site.xml and book.xml. thank you!

-- 
Reinhard

Re: Integrating auto-generated docs

[David Crossley <cr...@apache.org>]

Reinhard Poetz wrote:
> 
> Some of us started with generating docs out of Java sources (sitemap 
> components). I have to admit that I have no experience with this process 
> but I would like to integrate these reference docs into the new 
> documentation.

There is a rough explanation at
http://cocoon.apache.org/2.1/plan/review-sitemap-docs.html

What you refer to as "reference docs" below, are what you see now
on the website at /userdocs/$component/

> The problem is, how can I configure Forrest to use an 
> unknown number of docs and generate the menu *automatically*:

The Cocoon SitemapTask that generates those reference docs already
generates the book.xml files, which is the way Cocoon's forrest
uses to generate the navigation panels. Using book.xml is an old way
but it still works fine.

Anyway, my point is, that this is already being automatically generated.

--David

> +-+ new documentation
>   +-- getting started
>   +-- tutorial
>   +-+ reference docs
>     +-+ generators
>       +-- File Generator
>       +-- JXTemplateGenerator
>       +-- ...
>     +-- transformers
>     +-- ...
> 
> The only way I can think of is a hack using XML entities in site.xml and 
> auto-generating the content of files, that these entities are pointing to. 
> Or is there some better ("official supported") way of doing this?
> 
> -- 
> Reinhard