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: [all] Maven, help or hinderance?
Date Mon, 05 Dec 2005 00:20:09 GMT
On 12/4/05, Martin Cooper <martinc@apache.org> wrote:
> On 12/4/05, Steve Cohen <scohen@javactivity.org> wrote:
> >
> > Martin Cooper wrote:
> > > On 12/4/05, Steve Cohen <scohen@javactivity.org> wrote:
> > >
> > >>Phil Steitz wrote:
> > >>
> > >>>On 12/4/05, Steve Cohen <scohen@javactivity.org> wrote:
> > >>>
> > >>>
> > >>>>Henri Yandell wrote:
> > >>>>
> > >>>>
> > >>>>
> > >>>>>I turn the navigation off on Maven projects. Can't stand the
> > >>>>>project-reports, project-info roll-ups that make it harder to
find
> > >>>>>javadocs etc.
> > >>>>
> > >>>>Hear hear!  Javadocs are not a "project report" for anyone who uses
> > >>>>these sites.  This one we can't blame on Maven, though, can we?
 I
> > >>>>always assumed it was our setup of Maven.
> > >>>>
> > >>>
> > >>>What exactly is broken here?
> > >>>Sites that follow the instructions here
> > >>>http://jakarta.apache.org/commons/building.html
> > >>>or start with the sample nav here
> > >>>
> > >>
> > >>
> > http://svn.apache.org/repos/asf/jakarta/commons/proper/commons-build/trunk/navigation.xml.sample
> > >>
> > >>>will link to current and previous release javadoc from the top level
> > >>>nav.  Pretty much all maven-generated commons sites do this now.
> > >>>
> > >>>The real challenge is what Stephen mentioned and Brett responed to,
> > >>>which is how to maintain javadoc for past releases.  Now these files
> > >>>have to be manually pushed out and links custom coded in
> > >>>navigation.xml.
> > >>>
> > >>>Phil
> > >>>
> > >>>---------------------------------------------------------------------
> > >>>To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> > >>>For additional commands, e-mail: commons-dev-help@jakarta.apache.org
> > >>>
> > >>>
> > >>>
> > >>
> > >>You're missing the point here, Phil.  It's working as someone intended,
> > >>I'm sure, but the location of Javadocs buried under "Project Reports" is
> > >>bad from an end-user usability perspective.  Granted, consistency is a
> > >>good thing and frequent users may eventually learn, but it would be
> > >>better for javadocs to be a top-level menu item.  The "Javadoc Report"
> > >>is a report and is in the right place but the Javadocs themselves are
> > >>misplaced.
> > >
> > >
> > >
> > > It's trivial to just add a link to them in your navigation.xml file. See
> > the
> > > FileUpload, IO or Validator sites for examples.
> > >
> > > --
> > > Martin Cooper
> > >
> > >
> > > ---------------------------------------------------------------------
> > >
> > >>To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> > >>For additional commands, e-mail: commons-dev-help@jakarta.apache.org
> > >>
> > >>
> > >
> > >
> > Not quite so trivial.  The commons-io site evidently pushes two sets of
> > javadocs, one for "SVN latest" and another for the last official
> > release.  Net only has one and the one it has, although it's location is
> > named analogously to io's "SVN latest", actually points to net's last
> > official release.  So I suspect there's also some maven magic going on
> > here as well.
>
>
> I wasn't trying to solve the multiple Javadoc versions problem here (and I
> didn't do IO ;). If you look at FileUpload, all that has is an additional
> link in navigation.xml that points to the same Javadoc location as the
> Javadoc link under Project Reports. That's all I was suggesting.
>

Exactly, just as suggested in the example nav linked above.
Commons sites should be using that pattern, including the xml entities
for the common menus.  This is explained in the "Generating the site"
section of http://jakarta.apache.org/commons/building.html

I agree that javadoc should be prominent for commons components, but I
can understand why maven does not put it at the top level by default,
as lots of maven projects aren't libraries.  In any case, you can do
pretty much anything you want in navigation.xml.

Phil

---------------------------------------------------------------------
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