akarasulu 2004/02/03 19:45:23 Modified: www index.html irc.html www/related apache.html external.html index.html www/sandbox index.html www/subprojects index.html www/subprojects/sitedocs index.html Added: www/subprojects/sitedocs nav-template.txt Log: Added extensive documentation to the sitedocs section on how to integrate and deploy subprojects. Revision Changes Path 1.6 +23 -0 incubator-directory/www/index.html Index: index.html =================================================================== RCS file: /home/cvs/incubator-directory/www/index.html,v retrieving revision 1.5 retrieving revision 1.6 diff -u -r1.5 -r1.6 --- index.html 4 Feb 2004 02:13:39 -0000 1.5 +++ index.html 4 Feb 2004 03:45:22 -0000 1.6 @@ -760,6 +760,29 @@ + + + + + + + + + + + + Sitedocs + + + + + + The structure and organization of the entire website and how to + manage it is discribed here. + + + + 1.2 +6 -6 incubator-directory/www/irc.html Index: irc.html =================================================================== RCS file: /home/cvs/incubator-directory/www/irc.html,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- irc.html 4 Feb 2004 02:13:39 -0000 1.1 +++ irc.html 4 Feb 2004 03:45:22 -0000 1.2 @@ -563,13 +563,13 @@ - + - + Channel @@ -589,13 +589,13 @@ - + - + #directory @@ -617,13 +617,13 @@ - + - + #directory-dev 1.5 +2 -2 incubator-directory/www/related/apache.html Index: apache.html =================================================================== RCS file: /home/cvs/incubator-directory/www/related/apache.html,v retrieving revision 1.4 retrieving revision 1.5 diff -u -r1.4 -r1.5 --- apache.html 4 Feb 2004 02:13:40 -0000 1.4 +++ apache.html 4 Feb 2004 03:45:22 -0000 1.5 @@ -669,13 +669,13 @@ - + - + Name 1.5 +10 -10 incubator-directory/www/related/external.html Index: external.html =================================================================== RCS file: /home/cvs/incubator-directory/www/related/external.html,v retrieving revision 1.4 retrieving revision 1.5 diff -u -r1.4 -r1.5 --- external.html 4 Feb 2004 02:13:40 -0000 1.4 +++ external.html 4 Feb 2004 03:45:22 -0000 1.5 @@ -669,13 +669,13 @@ - + - + Name @@ -702,13 +702,13 @@ - + - + Name @@ -735,13 +735,13 @@ - + - + Name @@ -768,13 +768,13 @@ - + - + Name @@ -801,13 +801,13 @@ - + - + Name 1.5 +8 -8 incubator-directory/www/related/index.html Index: index.html =================================================================== RCS file: /home/cvs/incubator-directory/www/related/index.html,v retrieving revision 1.4 retrieving revision 1.5 diff -u -r1.4 -r1.5 --- index.html 4 Feb 2004 02:13:40 -0000 1.4 +++ index.html 4 Feb 2004 03:45:22 -0000 1.5 @@ -669,13 +669,13 @@ - + - + Name @@ -687,13 +687,13 @@ - + - + Apache Projects @@ -709,13 +709,13 @@ - + - + External Projects @@ -731,13 +731,13 @@ - + - + Directory Powered 1.5 +4 -4 incubator-directory/www/sandbox/index.html Index: index.html =================================================================== RCS file: /home/cvs/incubator-directory/www/sandbox/index.html,v retrieving revision 1.4 retrieving revision 1.5 diff -u -r1.4 -r1.5 --- index.html 4 Feb 2004 02:13:40 -0000 1.4 +++ index.html 4 Feb 2004 03:45:22 -0000 1.5 @@ -535,13 +535,13 @@ - + - + Project @@ -557,13 +557,13 @@ - + - + abc123 1.5 +35 -12 incubator-directory/www/subprojects/index.html Index: index.html =================================================================== RCS file: /home/cvs/incubator-directory/www/subprojects/index.html,v retrieving revision 1.4 retrieving revision 1.5 diff -u -r1.4 -r1.5 --- index.html 4 Feb 2004 02:13:40 -0000 1.4 +++ index.html 4 Feb 2004 03:45:22 -0000 1.5 @@ -622,13 +622,13 @@ - + - + Name @@ -640,13 +640,13 @@ - + - + @@ -673,13 +673,13 @@ - + - + @@ -706,13 +706,13 @@ - + - + @@ -746,13 +746,13 @@ - + - + @@ -782,13 +782,13 @@ - + - + @@ -817,6 +817,29 @@

+ + + + + + + + + + + + + + + + Sitedocs + + + + + + The structure and organization of the entire website and how to + manage it is discribed here. 1.5 +489 -0 incubator-directory/www/subprojects/sitedocs/index.html Index: index.html =================================================================== RCS file: /home/cvs/incubator-directory/www/subprojects/sitedocs/index.html,v retrieving revision 1.4 retrieving revision 1.5 diff -u -r1.4 -r1.5 --- index.html 4 Feb 2004 02:13:41 -0000 1.4 +++ index.html 4 Feb 2004 03:45:23 -0000 1.5 @@ -613,6 +613,47 @@

+ TODO +

+ + + + + + +
+ + +

Overview

@@ -737,6 +778,454 @@

+
+ +
+ + +

+ Subproject Integration Howto +

+ + +
+ + +

+ project.properties +

+ + +

+ + Add this to your maven project.properties at the top level of the + project: + +

+ +
+ 
  +maven.xdoc.date=left
  +maven.ui.banner.background=#FFFFFF
  +maven.xdoc.includeProjectDocumentation=no
  +maven.xdoc.poweredby.image=
  +maven.xdoc.jsl = file:/${basedir}/../../../sitedocs/trunk/sitedocs/src/etc/site.jsl
  +
+
+ +

+ + The last property is a relative reference to the + + + sitedocs/src/etc/site.jsl + + file. You can copy this if you want + into your own directory but I recommend you keep a reference since + it effects the sense of site continuity and the general look and feel + that is carried along on every subproject. There is no need to keep + them the same but it just might look better. Copying the file and + versioning it in a subproject directory will allow the top and + subproject sites to diverge. + +

+ +
+ +
+ + +

+ project.xml +

+ + +

+ + You have to make a couple of minor changes to the project.xml to make + the project and banner logos look the same on the TLP site and the + subproject site. Here's the set of tags and the values they should + be set to in order to maintain consistancy: + +

+ +
+ 
  +<name>Apache Directory Project</name>
  +<url>http://incubator.apache.org/directory</url>
  +<logo>http://incubator.apache.org/directory/images/apache-directory-logo.png</logo>
  +
  +<organization>
  +  <name>Apache Incubator</name>
  +  <url>http://incubator.apache.org</url>
  +  <logo>http://incubator.apache.org/directory/images/apache-incubator-logo.png</logo>
  +</organization>
  +
+
+ +

+ + The first stanza above should set the alt hints and link for the + project logo banner in the upper right hand corner using the following + graphic: + +

+ + + + + +

+ + The second stanza sets the organization logo which for now is the + Apache Incubator. The organization logo appears at the upper right + hand side, links to the incubator's main site and hold's alt hints + for the incubator. The following graphic will appear for this logo: + +

+ + + + + +
+ +
+ + +

+ Navigations +

+ + +

+ + Maintaining a consistant look and feel means perserving the top level + site's menus. To do this you'll need to work with the same navigation + and this requires the following navigation.xml template: + +

+ +
+ 
  +<?xml version="1.0" encoding="UTF-8"?>
  +
  +<project>
  +
  + <title>Apache Directory Project</title>
  +
  + <body>
  +
  +    <links>
  +      <item name="Apache" href="http://apache.org/"/>
  +      <item name="Directory" href="../../index.html"/>
  +      <item name="Eve" href="/index.html"/>
  +      <item name="LDAP" href="../ldap/index.html"/>
  +      <item name="Naming" href="../naming/index.html"/>
  +      <item name="Janus" href="../janus/index.html"/>
  +      <item name="Snickers" href="../snickers/index.html"/>
  +      <item name="Sitedocs" href="../sitedocs/index.html"/>
  +    </links>
  +
  +    <menu name="About Directory">
  +      <item name="Overview" href="../../index.html"/>
  +      <item name="Community" href="../../community/index.html"/>
  +      <item name="Latest News" href="../../news.html"/>
  +      <item name="Subprojects" href="../../subprojects/index.html">
  +        <item name="Eve" href="/index.html"/>
  +        <item name="LDAP" href="../ldap/index.html"/>
  +        <item name="Janus" href="../janus/index.html"/>
  +        <item name="Naming" href="../naming/index.html"/>
  +        <item name="Snickers" href="../snickers/index.html"/>
  +        <item name="Sitedocs" href="../sitedocs/index.html"/>
  +      </item>
  +      <item name="Documentation" href="../../doc/index.html"/>
  +    </menu>
  +
  +    <menu name="Resources">
  +      <item name="IRC" href="../../irc.html"/>
  +      <item name="Jira" href=
  +        "http://nagoya.apache.org/jira/secure/BrowseProject.jspa?id=10400"/>
  +      <item name="Wiki" href="http://wiki.apache.org/directory"/>
  +      <item name="Lists" href="../../mailing-lists.html"/>
  +      <item name="License" href="../../license.html"/>
  +      <item name="Sandbox" href="../../sandbox/index.html"/>
  +      <item name="Downloads" href="../../download.cgi"/>
  +      <item name="Subversion" href="../../svn.html"/>
  +      <item name="Related Projects" href="../../related/index.html"/>
  +    </menu>
  +
  + </body>
  +
  +</project>
  +
+
+ +

+ + You can download this navigation template from + + here + . Remember you take this + template and expand one of the subproject nodes to the number and kind + of subitems of your choosing by breaking up into a two part tag and + embedding more items within. For example this is how the Eve + subproject site navigation is structured: + +

+ +
+ 
  +        <item name="Eve" href="/index.html">
  +          <item name="Design" href="/design/index.html"/>
  +          <item name="Features" href="/features.html"/>
  +          <item name="Backend" href="/backend/index.html"/>
  +          <item name="Frontend" href="/frontend/index.html"/>
  +        </item>
  +
+
+ +
+ +
+ + +

+ Links +

+ + +

+ + Check out the section talking about links. All we do here is let you + know that you have to keep in mind the distance between the TLP site + documents and your subproject's site in the final deployed state. + Basically you have + + subprojects/[supproject-name] + + in the way. + That means two relative levels up to get to TLP resources while the + resources local to the project are still accessed as relative + resources. + +

+ +

+ + If you have questions just take a look at the links section and the + links in the navigation template above. If you still have questions + use trial and error until you develope a feel for it. Just generate + the document and see if it works locally by pointing a browser to it. + If you still need help post to the list. + +

+ +
+ +
+ +
+ + +

+ Deploying Site and Subprojects +

+ + +
+ + +

+ Incubator Site +

+ + +

+ + The entire Apache Incubator site is kept within CVS. This includes + generated files. There has to be a good Apache Incubator resource + for this in existance that explains how it is all organized. Until + I figure that out just follow along. + +

+ +

+ + Currently as a podling the Directory Project's resources are managed + under the Apache Incubator. The website is no exception. The + specific incubator module used is the + + incubator-directory + + CVS + module. I check it out like so: + +

+ +
+ 
  +cvs -d :ext:akarasulu@cvs.apache.org:/home/cvs co incubator-directory
  +
+
+ +

+ + This module contains a content directory: + + www + + . The final + content under + + www + + is served up by the Apache servers. The + module's + + www + + folder is checked out daily into the following + directory on minotaur.apache.org: + + + /www/incubator.apache.org/directory + + + +

+ +

+ + So all we have to do is generate the site out of our subversion + working directory and copy the Maven generated content into the + + + www + + folder of the CVS working copy for the incubator-directory + CVS module. That's a mouth full. + +

+ +

+ + Once the generated content is copied, the changes are committed. Then + deployers should ssh into minotaur and cd to the + + + /www/incubator.apache.org/directory + + to do an update like so: + +

+ +
+ 
  +cd /www/incubator.apache.org/directory
  +cvs update -d
  +
+
+ +

+ + Everyone within our team has access to this area. Anyone can deploy + the entire site or just a part of it this way. It's a pretty neat + setup and works well. + +

+ +
+ +
+ + +

+ Building Top Level Project Site +

+ + +

+ + Keep in mind that the subprojects contain their own documentation. + They hook into the TLP Site. The sitedocs project manages the TLP + site shell. Any documentation that is not specific to a subproject + goes here. + +

+ +

+ + Building the top level project site is really simple. You checkout + the sitedocs trunk form the subversion repository. Add, delete or + make changes to the xdocs that reside under the + + xdocs + + folder. + Once the changes are made run: + +

+ +
+ 
  +maven site          
  +
+
+ +

+ + This will generate the TLP site right under + + target/docs + + . + This does not generate the subproject content. To do this you'll + have to build the subproject documentation by using the same command + on the respective subproject. If all subprojects are configured as + documented here in the subproject integration section above then the + subproject build should copy the generated subproject documents over + to the respective + + target/docs/subprojects/[subproject] + + output + folder of the sitedocs module. + +

+ +

+ + If you're changes are to the TLP only without changes to the + subprojects then there is no need to build any subproject sites. If + you want to deploy one or more subproject site changes then go ahead + and build the subproject site for every subproject module. All the + results collect under the + + sitedocs/target/docs + + folder. + +

+ +

+ + The contents of the + + sitedocs/target/docs + + folder is what is + copied over into the + + incubator-directory/www + + folder and + committed into CVS. + +

+ +
+
1.1 incubator-directory/www/subprojects/sitedocs/nav-template.txt Index: nav-template.txt =================================================================== Apache Directory Project