Confluence Site Improvements

["Salazar, Alexander" <Sa...@GSB.Stanford.Edu>]

A left hand navigation to the confluence site would be a simple but strong improvement to the site.  What would be the easiest way to get this done?  

Since there seems to be broad agreement in the "Shiro API Discussion" thread that the confluence site should continue to be the main site and link to the auto-generated documentation, navigation could get hairy.  

I'd like to help with this (and other site improvements) but it seems that it requires a page be created at the space root and therefore Space Admin privileges.  

If I can't do it and someone else with the right privileges would like to help with this, here are the instructions.

http://confluence.atlassian.com/display/DOC/Adding+a+Navigation+Sidebar

And here's the menu I propose to the list.

Overview
-Welcome

Get Shiro
-Download
-Quickstart
-License

About Shiro
-What is Shiro
-Features
-Articles

Community
-Mailing Lists
-Forums 
-Issue Tracking

Project Documentation (This would be added once we have the documentation pages auto-generating)
- ...






-----Original Message-----
From: Les Hazlewood [mailto:les.hazlewood@anjinllc.com] 
Sent: Wednesday, September 09, 2009 12:05 PM
To: shiro-dev@incubator.apache.org
Subject: Re: Shiro API Documentation

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
<ka...@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<lh...@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
>> <ka...@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 <Cr...@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_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 <Cr...@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
>>>>>>>>> <ka...@gmail.com> wrote:
>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> On Fri, Sep 4, 2009 at 12:23 AM, Salazar,
>>>>>>>>>> Alexander<Sa...@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!
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>
>>>>> 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!
>>>>>
>>>>>
>>>>
>>>
>>
>