[
https://issues.apache.org/jira/browse/SHIRO-102?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Kalle Korhonen closed SHIRO-102.
--------------------------------
Resolution: Fixed
See Shiro's root pom.xml for exact configuration.
> Set-up AutoExport of Shiro documentation to the appropriate location
> --------------------------------------------------------------------
>
> Key: SHIRO-102
> URL: https://issues.apache.org/jira/browse/SHIRO-102
> Project: Shiro
> Issue Type: Task
> Components: Documentation
> Affects Versions: 1.0.0
> Reporter: Alex Salazar
> Assignee: Kalle Korhonen
> Fix For: 1.0.0
>
> Original Estimate: 2h
> Remaining Estimate: 2h
>
> In order to post documentation on the Shiro site, the documentation has to be
> exported onto some online space where the main site can link to it. Further,
> it needs to be set up such that the documentation is auto-exported with every
> build so that the shiro site is automatically kept up to date.
> Here is the email thread from the dev list that covers the issue in more
> detail:
> On Wed, Sep 9, 2009 at 4:43 PM, Les Hazlewood <l...@hazlewood.com> wrote:
> There we go - the 'incubator www site' is what I'm missing.
> It looks like this is what we need to know:
> http://www.apache.org/dev/project-site.html
> On Wed, Sep 9, 2009 at 1:26 PM, Kalle Korhonen <kalle.o.korho...@gmail.com>
> wrote:
> > Just a few examples of Maven-generated Apache project sites (many of
> > them are Maven-powered):
> > http://commons.apache.org/lang/
> > http://logging.apache.org/log4j/
> > http://tapestry.apache.org/tapestry5/
> > http://incubator.apache.org/chemistry/
> >
> > Note the last one is an incubator project. I suppose you just need a
> > directory on the incubator www site to publish the contents to.
> >
> > Kalle
> >
> >
> > On Wed, Sep 9, 2009 at 10:15 AM, Les Hazlewood<lhazlew...@apache.org> wrote:
> >> +1
> >>
> >> Mentors, how would we go about this process?
> >>
> >> I'm not familiar with where the generated site would be uploaded.
> >> I'm assuming after it is uploaded (by the build), that our wiki would
> >> just link to that location?
> >>
> >> Thanks,
> >>
> >> Les
> >>
> >> On Tue, Sep 8, 2009 at 6:56 PM, Kalle Korhonen
> >> <kalle.o.korho...@gmail.com> wrote:
> >>> I've always maintained that the best option is to combine aspects of
> >>> both a static (Maven) site and a wiki. Actually I managed to do
> >>> exactly that for Trails project, seamlessly mixing Maven site and
> >>> Confluence content with the help of Codehaus' clever site layout
> >>> renderer and a heavily customized Maven site skin. Basically Codehaus'
> >>> site renderer pulls content snippets out of confluence and puts them
> >>> together as one page (sort of a smart server-side include). However,
> >>> Shiro's not a Codehaus project and Maven 3 is not here yet. In the
> >>> meantime, I agree that Confluence space is probably easier to use as
> >>> the main site, but nevertheless we need a Maven site destination to
> >>> publish the javadocs and the rest of useful generated content (data
> >>> pulled from pom, quality reports, etc.) and that we can do in the
> >>> short term. Agree?
> >>>
> >>> Kalle
> >>>
> >>>
> >>> 2009/9/8 Tamás Cservenák <ta...@cservenak.net>:
> >>>> Yup,
> >>>> especially if you consider the upcoming maven3, and how it will
> >>>> redefine the site plugin... The site plugin as is now -- in maven
> >>>> 2.x line -- was generally a mistake. It is too coupled to core (or
> >>>> core is coupled to site plugin because of reporting, depends on how
> >>>> you look at it), and did not left place for any alternative
> >>>> reporting engine. This is what will change in
> >>>> maven3 regarding to this plugin.
> >>>>
> >>>> ~t~
> >>>>
> >>>> On Tue, Sep 8, 2009 at 5:57 AM, Craig L Russell
> >>>> <craig.russ...@sun.com>wrote:
> >>>>
> >>>>> Hi,
> >>>>>
> >>>>> I am inclined to agree with Tamas.
> >>>>>
> >>>>> From my experience, maven is great for getting something going
> >>>>> pretty quickly but I haven't seen it to be flexible enough to run the
> >>>>> entire site.
> >>>>> Confluence is both easy to use and powerful and allows for some
> >>>>> pretty nice customizations of the look and feel of the site.
> >>>>>
> >>>>> Craig
> >>>>>
> >>>>>
> >>>>> On Sep 7, 2009, at 12:14 PM, Tamás Cservenák wrote:
> >>>>>
> >>>>> 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_a...@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_a...@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.hazlew...@anjinllc.com
> >>>>>>> [mailto:les.hazlew...@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.russ...@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.korho...@gmail.com> wrote:
> >>>>>>>>>
> >>>>>>>>>>
> >>>>>>>>>> On Fri, Sep 4, 2009 at 12:23 AM, Salazar,
> >>>>>>>>>> Alexander<salazar_a...@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.russ...@sun.com P.S. A good JDO? O,
> >>>>>>>> Gasp!
> >>>>>>>>
> >>>>>>>>
> >>>>>>>>
> >>>>>>>
> >>>>> Craig L Russell
> >>>>> Architect, Sun Java Enterprise System http://db.apache.org/jdo
> >>>>> 408 276-5638 mailto:craig.russ...@sun.com P.S. A good JDO? O,
> >>>>> Gasp!
> >>>>>
> >>>>>
> >>>>
> >>>
> >>
> >
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
