commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Mark R. Diggory" <mdigg...@latte.harvard.edu>
Subject Re: documentation or site (was Re: [all] site generation)
Date Thu, 24 Jun 2004 14:51:19 GMT
For instance, each projects maven.xml could include the following 
instead of project.properties

  <available file="../commons-build/commons-site.jsl" 
property="commons.site.present"/>
  <j:if test="${commons.site.present}">       
      <j:set var="maven.xdoc.jsl" 
value="../commons-build/commons-site.jsl"/>
  </j:if>

Then if the jsl is absent, the site generated will have the defaults 
provided by mavens jsl.

Mark R. Diggory wrote:

> I would suggest the following.
>
> Up to this point we are doing an entity include of all the global 
> navigation entries from commons-build and setting a project.properly 
> to pick up and use the global jsl page. This is to maintain consistent 
> L&F of generated documentation. The major problem that arises is that 
> this interferes with all other build processes and one can't just 
> checkout thier individual project and work on it now.
>
> 1.) We want to maintain consistent L&F (but not at this cost).
>
> 2.) We should want to use default behaviors of Maven wherever possible 
> over customized plugin solutions that may not be supportable in future 
> versions etc.
>
> What I notice to date is that those of us working on "site" are not 
> fully embracing the "Leave it Maven" attitude that I think would make 
> all this alot easier. So we end up with customizations that are both 
> painful to maintain and cause problems for builders downstream. With 
> this in mind I have the following suggestions.
>
> While having all global menus in one place is great for the top level 
> site generation. It is a problem for individual projects. I recommend 
> setting up a two step generation process where "site" is presponsible 
> for updating a global-navigation.xml in each project whenever the top 
> level navigation is altered. This document would be generated for each 
> project from the commons-build/menu's content. This would be a goal in 
> commons-build/maven.xml that generated the global navigation files in 
> each project.
>
> This would save us headaches downstream an solve all the issues 
> developers are encountering with building distributions because there 
> would no longer be references to global commons-build files in each 
> project. Each project could then be built by its developers without 
> need to checkout commons-build.
>
> Another alternative is to generate the global and local menues as 
> separate "entities" such that the globals are included into the global 
> site jsl used to generate the top level site. Again, if your 
> publishing any of the subproject sites, you should already be checking 
> out the commons-build to get the common site.jsl that is used to 
> maintain the styles across the entire site. We should make the 
> inclusion of the jsl optional in each project so that it doesn't break 
> any part of the build if it can't be found. This mean moving the 
> parameterization "maven.xdoc.jsl=../commons-build/commons-site.jsl" 
> into the maven.xml within a jellyscript if statement that tests if the 
> files exists.
>
> I'll try to draw up some examples of this.
>
> -Mark
>
>
>
>
> Paul Libbrecht wrote:
>
>> This raises the problem of documentation vs site... maven has happily 
>> brought this together whereas this is indeed a problem.
>>
>> The case where this was observed was: jelly when checked-out over 
>> cvs, can't perform the dist goal, because it needs resources of 
>> commons-build as this is needed to build the site. However, a dist 
>> goal should be able to actually produce an amount of document on the 
>> version downloaded...
>>
>> Moreover, the documentation available through the web should, I 
>> believe, also be made in several versions, at least it's the case for 
>> major things like Tomcat.
>>
>> So... should we not try to separate the two ?
>>
>> paul
>>
>>
>> On 23-Jun-04, at 22:21 Uhr, Stephen Colebourne wrote:
>>
>>>>> Usually you run Maven locally and upload the site manually. I'm 
>>>>> not sure
>>>>> anyone is running a cron for it, and I'd recommend not doing so 
>>>>> because
>>>>> the published site ends up in line with CVS and not with your latest
>>>>> stable release. User's then get very confused.
>>>>
>>>>
>>>> You are right, only the developpement pages should be refreshed then
>>>> (changes, commits, activity, tests...). The documentation should stick
>>>> to the latest stable release. I have no idea how to achieve this with
>>>> Maven though ;)
>>>
>>>
>>> See [collections]. The maven.xml has a full script for building 
>>> javadoc of
>>> old versions (tested on Maven RC1). The navigation.xml has explicit 
>>> links to
>>> each of the generated javadocs.
>>
>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
>> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>>
>
>
>------------------------------------------------------------------------
>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
>For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>



Mime
View raw message