You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Gilles Sadowski <gi...@harfang.homelinux.org> on 2012/12/30 23:45:55 UTC
[Math] Location of the API docs on the web site (Was: svn commit:
r1426997 - ...)
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! :)
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 (?).]
Regards,
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [Math] Location of the API docs on the web site
Posted by Phil Steitz <ph...@gmail.com>.
On 12/31/12 4:37 PM, Gilles Sadowski wrote:
>>> [...]
>>>
>>> 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.
> It was just an observation; not an invitation to manage more with resources
> which we don't have...
>
>> 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?
> If the site exists (generated locally), then this command uploads it.
> But if the final date was today, it's too late...
> Anyways, the 3.1 docs is currently quite close to "latest".
I managed to sneak in a deploy, including even the 90+-minute
cobertura report earlier this evening.
Happy New Year!
Phil
>
> 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
Re: [Math] Location of the API docs on the web site
Posted by Gilles Sadowski <gi...@harfang.homelinux.org>.
> > [...]
> >
> > 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.
It was just an observation; not an invitation to manage more with resources
which we don't have...
> 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?
If the site exists (generated locally), then this command uploads it.
But if the final date was today, it's too late...
Anyways, the 3.1 docs is currently quite close to "latest".
Gilles
> [...]
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [Math] Location of the API docs on the web site
Posted by Phil Steitz <ph...@gmail.com>.
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
Re: [Math] Location of the API docs on the web site
Posted by Gilles Sadowski <gi...@harfang.homelinux.org>.
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.
> 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
Re: [Math] Location of the API docs on the web site (Was: svn commit:
r1426997 - ...)
Posted by Phil Steitz <ph...@gmail.com>.
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