maven site generation & genesis

[Joe Bohn <jo...@earthlink.net>]

I've been making some changes to Genesis 1.5-SNAPSHOT to get maven site 
generation working a little bit better and fix a few other things.  All 
of this is because there were still some maven site generation issues 
after releasing samples.  I think I have things working better now ... 
but I have some questions:

- Regarding the site.xml ... it looked to me like the original intent 
was to leverage completely the site.xml from genesis.  However, I could 
never get this working correctly to include the header for the generated 
site.  As a result ... I ended up including some of the same site.xml 
content in samples such as the skin and banner definition. Is that a 
problem?

- Genesis:  When we were getting samples out the door I ended up 
including some temporary junk in the sample pom/site.  I've now removed 
this and made some minor changes to genesis/branches/genesis-1.x. 
Should I look at releasing Genesis 1.5 until 2.0 is complete or should 
we put all emphasis on 2.0?  What is the current status of 2.0?   BTW .. 
I also noticed that generating a site for genesis 2.0-SNAPSHOT itself 
has some issues .... something else to look into.

- Specs:  I've also made some similar changes locally for specs.  I 
think these will produce more correct maven sites.  However, the would 
require changes to depend on a newer Genesis and would require releasing 
a new specs-parent (1.6).  I don't want to include these snapshot 
dependencies which would hinder the ability to release specs for now ... 
so I'm waiting on the Genesis decision.  If we want to push out a 
Genesis 1.5 rc and get that up for vote.

General:  Is this really worth the effort?  It seems that we haven't put 
much of an emphasis on maven sites.  Is this because there were problems 
generating them or because we don't see much value?  Most of what we 
have out there now is 2 years old (see 
http://cwiki.apache.org/GMOxDEV/maven-generated-documentation.html). 
It think there are some concerns of how useful these are, particularly 
for multi-project release (like server).  The site information generated 
is per project and doesn't provide a good overview. IIUC, this can be 
aggregated for some if not all things (like javadoc).  In the past we 
have provided independent javadoc in addition to the site (which I 
suspect is why, I suspect that the latest javadoc available for the 
server from our site if for 2.0.1).  Should we focus energy on getting 
independent javadoc release, improve maven site generation and leverage 
that for javadoc/xrefs, or both?

Joe

Re: maven site generation & genesis

[Joe Bohn <jo...@earthlink.net>]

Donald Woods wrote:
> In-line.
> 
> 
> Joe Bohn wrote:
>>
>> I've been making some changes to Genesis 1.5-SNAPSHOT to get maven 
>> site generation working a little bit better and fix a few other 
>> things.  All of this is because there were still some maven site 
>> generation issues after releasing samples.  I think I have things 
>> working better now ... but I have some questions:
>>
>> - Regarding the site.xml ... it looked to me like the original intent 
>> was to leverage completely the site.xml from genesis.  However, I 
>> could never get this working correctly to include the header for the 
>> generated site.  As a result ... I ended up including some of the same 
>> site.xml content in samples such as the skin and banner definition. Is 
>> that a problem?
>>
>> - Genesis:  When we were getting samples out the door I ended up 
>> including some temporary junk in the sample pom/site.  I've now 
>> removed this and made some minor changes to 
>> genesis/branches/genesis-1.x. Should I look at releasing Genesis 1.5 
>> until 2.0 is complete or should we put all emphasis on 2.0?  What is 
>> the current status of 2.0?   BTW .. I also noticed that generating a 
>> site for genesis 2.0-SNAPSHOT itself has some issues .... something 
>> else to look into.
> 
> Yes, we should release 1.5, so future maintenance releases of existing 
> 2.0/2.1 server, samples and specs can use it (there will be a 2.1.4 
> Server release, just a mater of when...)

I was leaning that way too. In my very poorly worded sentence below I 
intended to say "I can create a Genesis 1.5 rc and get that up for a 
vote".  I'll go ahead and do that now.  If there are any objections to 
that we can deal with in the vote/discussion.

> 
>>
>> - Specs:  I've also made some similar changes locally for specs.  I 
>> think these will produce more correct maven sites.  However, the would 
>> require changes to depend on a newer Genesis and would require 
>> releasing a new specs-parent (1.6).  I don't want to include these 
>> snapshot dependencies which would hinder the ability to release specs 
>> for now ... so I'm waiting on the Genesis decision.  If we want to 
>> push out a Genesis 1.5 rc and get that up for vote.
>>
>> General:  Is this really worth the effort?  It seems that we haven't 
>> put much of an emphasis on maven sites.  Is this because there were 
>> problems generating them or because we don't see much value?  Most of 
>> what we have out there now is 2 years old (see 
>> http://cwiki.apache.org/GMOxDEV/maven-generated-documentation.html). 
>> It think there are some concerns of how useful these are, particularly 
>> for multi-project release (like server).  The site information 
>> generated is per project and doesn't provide a good overview. IIUC, 
>> this can be aggregated for some if not all things (like javadoc).  In 
>> the past we have provided independent javadoc in addition to the site 
>> (which I suspect is why, I suspect that the latest javadoc available 
>> for the server from our site if for 2.0.1).  Should we focus energy on 
>> getting independent javadoc release, improve maven site generation and 
>> leverage that for javadoc/xrefs, or both?
> 
> Some users have asked for updated javadoc, so lets give it one more try 
> before we abandon site generation.

FYI, I'm also looking into what we need to do to update the javadoc on 
the website (independent of the maven site).  I'd love to eliminate one 
of these but in the until we can get a server site generated I think it 
makes sense to release some freah javadoc for 2.1.3.

> 
> 
>>
>> Joe
>>
>>
> 

Re: maven site generation & genesis

[Donald Woods <dw...@apache.org>]

In-line.


Joe Bohn wrote:
> 
> I've been making some changes to Genesis 1.5-SNAPSHOT to get maven site 
> generation working a little bit better and fix a few other things.  All 
> of this is because there were still some maven site generation issues 
> after releasing samples.  I think I have things working better now ... 
> but I have some questions:
> 
> - Regarding the site.xml ... it looked to me like the original intent 
> was to leverage completely the site.xml from genesis.  However, I could 
> never get this working correctly to include the header for the generated 
> site.  As a result ... I ended up including some of the same site.xml 
> content in samples such as the skin and banner definition. Is that a 
> problem?
> 
> - Genesis:  When we were getting samples out the door I ended up 
> including some temporary junk in the sample pom/site.  I've now removed 
> this and made some minor changes to genesis/branches/genesis-1.x. Should 
> I look at releasing Genesis 1.5 until 2.0 is complete or should we put 
> all emphasis on 2.0?  What is the current status of 2.0?   BTW .. I also 
> noticed that generating a site for genesis 2.0-SNAPSHOT itself has some 
> issues .... something else to look into.

Yes, we should release 1.5, so future maintenance releases of existing 
2.0/2.1 server, samples and specs can use it (there will be a 2.1.4 
Server release, just a mater of when...)

> 
> - Specs:  I've also made some similar changes locally for specs.  I 
> think these will produce more correct maven sites.  However, the would 
> require changes to depend on a newer Genesis and would require releasing 
> a new specs-parent (1.6).  I don't want to include these snapshot 
> dependencies which would hinder the ability to release specs for now ... 
> so I'm waiting on the Genesis decision.  If we want to push out a 
> Genesis 1.5 rc and get that up for vote.
> 
> General:  Is this really worth the effort?  It seems that we haven't put 
> much of an emphasis on maven sites.  Is this because there were problems 
> generating them or because we don't see much value?  Most of what we 
> have out there now is 2 years old (see 
> http://cwiki.apache.org/GMOxDEV/maven-generated-documentation.html). It 
> think there are some concerns of how useful these are, particularly for 
> multi-project release (like server).  The site information generated is 
> per project and doesn't provide a good overview. IIUC, this can be 
> aggregated for some if not all things (like javadoc).  In the past we 
> have provided independent javadoc in addition to the site (which I 
> suspect is why, I suspect that the latest javadoc available for the 
> server from our site if for 2.0.1).  Should we focus energy on getting 
> independent javadoc release, improve maven site generation and leverage 
> that for javadoc/xrefs, or both?

Some users have asked for updated javadoc, so lets give it one more try 
before we abandon site generation.


> 
> Joe
> 
>