commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Steitz <phil.ste...@gmail.com>
Subject Re: [Math] Location of the API docs on the web site (Was: svn commit: r1426997 - ...)
Date Mon, 31 Dec 2012 00:31:19 GMT
On 12/30/12 2:45 PM, Gilles Sadowski wrote:
> On Sun, Dec 30, 2012 at 09:50:11PM -0000, psteitz@apache.org wrote:
>> Author: psteitz
>> Date: Sun Dec 30 21:50:11 2012
>> New Revision: 1426997
>>
>> URL: http://svn.apache.org/viewvc?rev=1426997&view=rev
>> Log:
>> Documented commons.componentid ambiguiity and workaround.
>>
>> Modified:
>>     commons/proper/math/trunk/doc/release/release.howto.txt
>>     commons/proper/math/trunk/pom.xml
>>
>> Modified: commons/proper/math/trunk/doc/release/release.howto.txt
>> URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/doc/release/release.howto.txt?rev=1426997&r1=1426996&r2=1426997&view=diff
>> ==============================================================================
>> --- commons/proper/math/trunk/doc/release/release.howto.txt (original)
>> +++ commons/proper/math/trunk/doc/release/release.howto.txt Sun Dec 30 21:50:11 2012
>> @@ -70,7 +70,10 @@ to the SVN repository. Once the release 
>>  The "download" page template is located at "src/site/xdoc/download_math.xml".
>>  This file is updated automatically by running the command:
>>  
>> -  $ mvn commons:download-page
>> +  $ mvn commons:download-page -Dcommons.componentid=math
>> +
>> +The command-line property override is necessary because the download plugin
>> +expects the project name in the componentid property.
> How neat that is! :)

I stole the pom comment from [lang].  We should probably fix the
ambiguity in the property name somehow - either say "componentid"
means "project name" (so osgi plugin or what gets passed to it
changes) or define a new property that *is* project name and change
the download plugin to use that.
>
> On a related note: when creating the site, the generated Javadoc ends up in
> a directory whose parent is "apidocs".  E.g. the Javadoc for release 3.1 is
> in
>   http://commons.apache.org/math/apidocs/index.html
>
> Doc for older releases are in a directory whose parent is named after the
> release identifier, e.g. doc for 3.0 is in
>   http://commons.apache.org/math/api-3.0/index.html
>
> I think that it would be more flexible that the "site" target creates a
> directory with the appropriate version id.
> That way, we would avoid the repetition of the problem raised in issue
>   https://issues.apache.org/jira/browse/MATH-912
>
> Could this be fixed with a similar trick?
> [It would also require to change the links in the user guide: "apidocs"
> appears explicitly there. There should probably be a variable instead, which
> will be set as the document is processed to create the HTML page (?).]

I can't find a way to alter the destination directory for the
javadoc on the command line.  You can do it in a profile, though,
using the reportOutputDirectory configuration property.  What we
have done in the past is to just manually create the api-xxx
directory on p.a.o and have the site link point there.  I almost did
that this afternoon; but thought we might wait until we have sorted
out the svn pub-sub stuff.  I will do this tomorrow if all are OK
with it.

I think the model followed by most other components where you have a
"latest javadoc" link that points to what mvn javadoc:javadoc
generates from trunk is good.  That means that when you cut a
release you do the following additional manual steps:

0) copy (or just rename) release javadoc to
/www/commons.apache.org/math/api-xxx where xxx is the release you
just cut.
1) add a link in site.xml that points to the release javadoc.

Unfortunately, the whole p.a.o site stuff is about to turn into a
pumpkin, so we are going to need an svn pub-sub way to accomplish
the same thing assuming we want to keep things this way.

Thanks for documenting a release recipe that works.

Phil

>
>
> Regards,
> Gilles
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message