shiro-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tamás Cservenák <ta...@cservenak.net>
Subject Re: Shiro API Documentation
Date Mon, 07 Sep 2009 19:14:50 GMT
Hi,

I would not recommend using (and tying to) maven-site-plugin.... You have
plenty of better alternatives: http://xsite.codehaus.org/ or Confluence
(either publishing it directly or for authoring only, and exporting +
post-processing pages), etc.
Maven Site plugin is generally good to have reports (Javadoc, coverage, etc)
generated, but using it for main site is something I would not recommend.

Thanks,
~t~


On Mon, Sep 7, 2009 at 6:05 PM, Salazar, Alexander <
Salazar_Alex@gsb.stanford.edu> wrote:

> I'd like to get an opinion on this Maven site how you'd like to move
> forward so that I can starting working on the Shiro site and web
> documentation.
>
> Since I'm new to Maven, I took sometime this weekend to play with it and
> its site plugin.  Not sure if this project ever used it before but its
> impressive how easy it makes building documentation into a site.
>
> Though I'm still not sure of the pros and cons for a wiki primary site, I
> built out a basic maven-based primary site for shiro and submit to you these
> pros/cons.
>
> Pros
> 1. Build many of the pages needed directly from your pom
> 2. Easy to keep documentation linked and synced
> 3. All the content would be in your src directory under site-- it would all
> be in one place
> 4. Templates/Skins are easy to build (kinda) and easy to apply throughout
> the site
> 5. Easy to layout like other Apache projects which will lend
> easy-of-navigation and more credibility to the site.
>
> Cons
> 1. Unique formatting sytanx for pages and skins (APT, FML, Velocity, etc)
> 2. Not as malleable as HTML and CSS
> 3. Not as easy to edit content as a wiki
> 4. To see any change to the site, the whole thing needs to be rebuilt--  or
> so it seems.
>
> Attached's a screenshot of the basic site using the basic skin.
>
> -Alex
>
> -----Original Message-----
> From: Salazar, Alexander [mailto:Salazar_Alex@GSB.Stanford.Edu]
> Sent: Friday, September 04, 2009 2:10 PM
> To: shiro-dev@incubator.apache.org
> Subject: RE: Shiro API Documentation
>
> I'd be happy to help with the site but I'm not clear on the value of a
> maven site compared to the wiki as the main site.
>
> -----Original Message-----
> From: les.hazlewood@anjinllc.com [mailto:les.hazlewood@anjinllc.com] On
> Behalf Of Les Hazlewood
> Sent: Friday, September 04, 2009 11:59 AM
> To: shiro-dev@incubator.apache.org
> Subject: Re: Shiro API Documentation
>
> I personally like the idea of using the wiki as our primary content
> mechanism, but I would like it to look better.  I understand that's
> not difficult to do - we'd just need to apply a site template.  Alex,
> is this something you'd be interested in helping with?
>
> But let's say that we have the wiki exporting properly - what is the
> best way to reference build artifacts and static resources from within
> the wiki (like the JavaDocs)?  Would we just export the site wherever
> we want and then link to it from within the wiki?  Where would the
> physical files reside?
>
> - Les
>
> On Fri, Sep 4, 2009 at 1:59 PM, Craig L Russell <Craig.Russell@sun.com>
> wrote:
> >
> > On Sep 4, 2009, at 7:26 AM, Les Hazlewood wrote:
> >
> >> Sure, I think that's a good idea.
> >>
> >> Mentors - where can this site be hosted and how do we automate the
> >> push to that location?
> >
> > The project needs to decide whether to publish the Maven-generated site
> as
> > "The Shiro Site", or whether to use the confluence wiki as the official
> > site.
> >
> > The place to publish the result is http://incubator.apache.org/shiro
> >
> > Look at http://incubator.apache.org/ki/ for what is currently being
> done.
> >
> > Once the project decides on the strategy for generating content,
> > infrastructure can help with the mechanical details of automatically
> > generating and pushing the site live.
> >
> > Craig
> >>
> >> Thanks,
> >>
> >> Les
> >>
> >> On Fri, Sep 4, 2009 at 10:17 AM, Kalle Korhonen
> >> <kalle.o.korhonen@gmail.com> wrote:
> >>>
> >>> On Fri, Sep 4, 2009 at 12:23 AM, Salazar,
> >>> Alexander<Salazar_Alex@gsb.stanford.edu> wrote:
> >>>>
> >>>> Even though a 1.0 has not yet been released, I think it would be
> helpful
> >>>> to get to-date Shiro API documentation online and available.
> >>>> According to Les, "Maven auto-generates not just the API
> documentation,
> >>>> but an entire site.  However, we've only been using the wiki thus far.
>  We
> >>>> would have to get the auto-export of this generated documentation set
> up
> >>>> based on the automated build process."
> >>>>
> >>>> What would be the best way to go about this?  Do you agree that it
> would
> >>>> be valuable prior to the 1.0 release?
> >>>
> >>> The best way would be to publish the Maven site (it includes the
> >>> javadocs by default). I already had a thread on this topic, see "Plans
> >>> to publish javadocs & Maven site continuously/nightly?". The question
> >>> Les had whether there were any guidelines regarding publishing the
> >>> documentation while a project is still in incubator but no responses
> >>> (though I know at least CXF was publishing all docs while in incubator
> >>> so I don't think it's an issue). Once we know *where* we could publish
> >>> the site, we could set up a Hudson job and then incrementally improve
> >>> the contents.
> >>>
> >>> Kalle
> >>>
> >
> > Craig L Russell
> > Architect, Sun Java Enterprise System http://db.apache.org/jdo
> > 408 276-5638 mailto:Craig.Russell@sun.com
> > P.S. A good JDO? O, Gasp!
> >
> >
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message