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
Date Mon, 31 Dec 2012 15:36:45 GMT
On 12/31/12 5:06 AM, Gilles Sadowski wrote:
> On Sun, Dec 30, 2012 at 04:31:19PM -0800, Phil Steitz wrote:
>> 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.
> Done. [Just in case, although there isn't any time left before that site is
> frozen, so that the "Latest API" link (see below) will never make it there.]
>
>> 1) add a link in site.xml that points to the release javadoc.
> Done in revision 1427112.
> Also added a "Latest API".
>
>
> The slight problem with the above is that there is only one version of the
> user guide, and it refers (links) to the "apidocs" directory (i.e. "Latest
> API" next time the site is generated).
> 1. The user guide might not be in sync (i.e. giving examples that use an
>    outdated API) with the Javadoc it points to.
> 2. Some (most?) users might prefer to use the latest official release, but
>    when reading the user guide, they will be referred to classes or method
>    that may not exist in that version.

Here again, the maybe not-clearly-communicated enough convention up
to now has been the live site corresponds to active development
(i.e. trunk); so examples and api docs in the user guide should be
"latest."  We ship enough with the source release to generate the
user guide for a release, so if users want the guide for the release
they are using, they can generate it from source.  In the old, old
days, we used to ship the full site with the binary distro, which
included the user guide.  I guess we could consider publishing
versioned user guides, but that is yet more content to manage on the
web site.

I think its worth sneaking in a final deploy before pumpkin time to
get latest javadoc (and links in the user guide) up.  Does mvn
site:deploy still work to do that?

Phil
>
>> 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.
> Thanks,
> 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