directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From akaras...@apache.org
Subject svn commit: rev 6497 - incubator/directory/sitedocs/trunk/sitedocs/xdocs/subprojects/sitedocs
Date Wed, 04 Feb 2004 08:50:37 GMT
Author: akarasulu
Date: Wed Feb  4 00:50:36 2004
New Revision: 6497

Added:
   incubator/directory/sitedocs/trunk/sitedocs/xdocs/subprojects/sitedocs/hyperlink-management.xml
   incubator/directory/sitedocs/trunk/sitedocs/xdocs/subprojects/sitedocs/maven-changes.xml
   incubator/directory/sitedocs/trunk/sitedocs/xdocs/subprojects/sitedocs/sitedoc-deployment.xml
Modified:
   incubator/directory/sitedocs/trunk/sitedocs/xdocs/subprojects/sitedocs/index.xml
   incubator/directory/sitedocs/trunk/sitedocs/xdocs/subprojects/sitedocs/navigation.xml
Log:
Cleaning up by breaking stuff apart


Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/subprojects/sitedocs/hyperlink-management.xml
==============================================================================
--- (empty file)
+++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/subprojects/sitedocs/hyperlink-management.xml
Wed Feb  4 00:50:36 2004
@@ -0,0 +1,133 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<document>
+  <properties>
+    <author email="akarasulu@apache.org">Alex Karasulu</author>
+    <title>Apache Directory Project: </title>
+  </properties> 
+  
+  <body>
+    <section name="Links Howto">
+      <p>
+        All links to documents within the same subproject are relative to that 
+        subproject.  Links to resources outside the subproject must take into
+        account the relative position of the target directory the subproject's
+        generated content is copied into.
+      </p>
+      
+      <p>
+        For example the 'directory' link in the sitedocs project is simply
+        '/index.html'.  The same 'directory' line in the Eve subproject will
+        be '../../index.html'.  This is because the Eve project's generated
+        content ultimately resides two directories deep with the sitedocs 
+        project's document root here: './subprojects/eve'.  It takes a 
+        '../../' to get to the index.html that is the home page for the TLP
+        site.
+      </p>
+      
+      <p>
+        Links to Apache, Directory, Eve, LDAP, Naming, Janus, Snickers and
+        Sitedocs must be maintained by all subprojects to keep the overall
+        site consistant.
+      </p>
+    </section>
+    
+      <section name="Navigations">
+        <p>
+          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:
+        </p>
+        
+        <source>
+&lt;?xml version="1.0" encoding="UTF-8"?&gt;
+
+&lt;project&gt;
+
+ &lt;title&gt;Apache Directory Project&lt;/title&gt;
+
+ &lt;body&gt;
+
+    &lt;links&gt;
+      &lt;item name="Apache" href="http://apache.org/"/&gt;
+      &lt;item name="Directory" href="../../index.html"/&gt;
+      &lt;item name="Eve" href="/index.html"/&gt;
+      &lt;item name="LDAP" href="../ldap/index.html"/&gt;
+      &lt;item name="Naming" href="../naming/index.html"/&gt;
+      &lt;item name="Janus" href="../janus/index.html"/&gt;
+      &lt;item name="Snickers" href="../snickers/index.html"/&gt;
+      &lt;item name="Sitedocs" href="../sitedocs/index.html"/&gt;
+    &lt;/links&gt;
+
+    &lt;menu name="About Directory"&gt;
+      &lt;item name="Overview" href="../../index.html"/&gt;
+      &lt;item name="Community" href="../../community/index.html"/&gt;
+      &lt;item name="Latest News" href="../../news.html"/&gt;
+      &lt;item name="Subprojects" href="../../subprojects/index.html"&gt;
+        &lt;item name="Eve" href="/index.html"/&gt;
+        &lt;item name="LDAP" href="../ldap/index.html"/&gt;
+        &lt;item name="Janus" href="../janus/index.html"/&gt;
+        &lt;item name="Naming" href="../naming/index.html"/&gt;
+        &lt;item name="Snickers" href="../snickers/index.html"/&gt;
+        &lt;item name="Sitedocs" href="../sitedocs/index.html"/&gt;
+      &lt;/item&gt;
+      &lt;item name="Documentation" href="../../doc/index.html"/&gt;
+    &lt;/menu&gt;
+
+    &lt;menu name="Resources"&gt;
+      &lt;item name="IRC" href="../../irc.html"/&gt;
+      &lt;item name="Jira" href=
+        "http://nagoya.apache.org/jira/secure/BrowseProject.jspa?id=10400"/&gt;
+      &lt;item name="Wiki" href="http://wiki.apache.org/directory"/&gt;
+      &lt;item name="Lists" href="../../mailing-lists.html"/&gt;
+      &lt;item name="License" href="../../license.html"/&gt;
+      &lt;item name="Sandbox" href="../../sandbox/index.html"/&gt;
+      &lt;item name="Downloads" href="../../download.cgi"/&gt;
+      &lt;item name="Subversion" href="../../svn.html"/&gt;
+      &lt;item name="Related Projects" href="../../related/index.html"/&gt;
+    &lt;/menu&gt;
+
+ &lt;/body&gt;
+
+&lt;/project&gt;
+        </source>
+        
+        <p>
+          You can download this navigation template from 
+          <a href="./nav-template.txt">here</a>.  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:
+        </p>
+        
+        <source>
+        &lt;item name="Eve" href="/index.html"&gt;
+          &lt;item name="Design" href="/design/index.html"/&gt;
+          &lt;item name="Features" href="/features.html"/&gt;
+          &lt;item name="Backend" href="/backend/index.html"/&gt;
+          &lt;item name="Frontend" href="/frontend/index.html"/&gt;
+        &lt;/item&gt;
+        </source>
+      </section>
+      
+      <section name="Links">
+        <p>
+          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 <b>subprojects/[supproject-name]</b> 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.
+        </p>
+        
+        <p>
+          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.
+        </p>
+      </section>
+  </body>
+</document>

Modified: incubator/directory/sitedocs/trunk/sitedocs/xdocs/subprojects/sitedocs/index.xml
==============================================================================
--- incubator/directory/sitedocs/trunk/sitedocs/xdocs/subprojects/sitedocs/index.xml	(original)
+++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/subprojects/sitedocs/index.xml	Wed Feb
 4 00:50:36 2004
@@ -6,457 +6,59 @@
   </properties>
 
   <body>
-    
-    <section name="TODO">
-      <ul>
-        <li>
-          Separate out these sections into their own pages and make this
-          page an overview page with a listing of topics in a table.  Too
-          much here in one place.
-        </li>
-        
-        <li>
-          Figure out what to add here as the guys use this to add their own
-          subproject sections.  Refine it and make it flow better.
-        </li>
-        
-        <li>
-          Spell and grammar check it.
-        </li>
-      </ul>
-    </section>
-    
     <section name="Overview">
       <p>
-        This project documents what is to be the umbrella website for all
-        Directory Project Sub-Projects.  There are a few rules and information
-        that is needed by Sub-Project developers in order to integrate/plugin
-        their Sub-Project documentation with this website.  
+        This subproject contains documents of the top level website linking 
+        together all subprojects.  There are a few rules and some information
+        that is needed by subproject developers in order to integrate/plugin
+        their subproject documentation with this TLP website.  We cover these
+        topics here.
       </p> 
       
-      <p>
-        We use maven and the xdoc format to manage site documents and site
-        generation.  The layout for the top level site is managed here in this
-        project.  This is a subproject area which is where subproject content
-        is deposited.  In case this does not happen correctly some stubs have 
-        been left in place of the subproject.  Here's where we keep subproject
-        xdoc stubs:
-      </p>
-      <source>
-sitedocs/xdocs/subprjects
-    ./eve
-    ./ldap     
-    ./janus
-    ./naming
-    ./snickers
-    ./sitedocs
-      </source>
-      
-      <p>
-        Obviously, rather than use stubs, the sitedocs subproject area will 
-        contain actual content which this page is part of.  These directories
-        as mentioned before contain stubs.  When the top level site is generated
-        the html created is deposited int the target/docs directory of the 
-        sitedocs project directory here: 
-      </p>
-      
-      <source>directory/sitedocs/trunk/sitedocs/target/docs</source>
-      
-      <p>
-        It is the reponsibility of subprojects to generate their own content 
-        and copy it over to their appropriate directory within the subprojects
-        directory.  The Eve subproject for example does this using a post goal
-        within the maven.xml project like so to copy its site documentation:
-      </p>
-      
-      <source>
-  &lt;postGoal name="site"&gt;
-    &lt;attainGoal name="server:copy-images"/&gt;
-    &lt;attainGoal name="subproject:collectdocs"/&gt;
-  &lt;/postGoal&gt;
-
-  &lt;goal name="subproject:collectdocs"&gt;
-    &lt;copy toDir="../../../sitedocs/trunk/sitedocs/target/docs/subprojects/eve"&gt;
-      &lt;fileSet dir="${basedir}/target/docs"&gt;
-        &lt;include name="**"/&gt;
-      &lt;/fileSet&gt;
-    &lt;/copy&gt;
-  &lt;/goal&gt;
-      </source>
-      
-      <p>
-        This however is not the only requirement.  As we'll see to maintain
-        consistancy throughout the site subproject documentation needs to 
-        manage links, manage the same navigations, set properties in maven 
-        and its pom.
-      </p>
-    </section>
-    
-    <section name="Links Howto">
-      <p>
-        All links to documents within the same subproject are relative to that 
-        subproject.  Links to resources outside the subproject must take into
-        account the relative position of the target directory the subproject's
-        generated content is copied into.
-      </p>
-      
-      <p>
-        For example the 'directory' link in the sitedocs project is simply
-        '/index.html'.  The same 'directory' line in the Eve subproject will
-        be '../../index.html'.  This is because the Eve project's generated
-        content ultimately resides two directories deep with the sitedocs 
-        project's document root here: './subprojects/eve'.  It takes a 
-        '../../' to get to the index.html that is the home page for the TLP
-        site.
-      </p>
-      
-      <p>
-        Links to Apache, Directory, Eve, LDAP, Naming, Janus, Snickers and
-        Sitedocs must be maintained by all subprojects to keep the overall
-        site consistant.
-      </p>
-    </section>
-    
-    <section name="Subproject Integration Howto">
-      <p>
-        At the present time there are stubs that have been placed
-        into the respective directories for the subprojects.  So under <b>
-        sitedocs/xdocs/subprojects</b> where subproject directories are 
-        contained a stub <b><em>index.xml</em></b> and <b><em>navigation.xml
-        </em></b> will be found.
-      </p>
-      
-      <p>
-        We have done this to prevent users from encountering broken links on the
-        site.  Once you have built your subproject's site and are sure it works
-        remove the respective stubs for your subproject.  If you do not do so
-        your content may be over written by the stubs if someone deploys the
-        top level site without generating your subproject's content.  So please
-        rm these stubs from the repository once your subproject is up. 
-      </p>
-      
-      <p>
-        Below we point out all the files and changes that need to be made in
-        order to make your subproject integrate into the top level site to
-        maintain a consistant look and feel.
-      </p>
-      
-      <subsection name="project.properties">
-        <p>
-          Add this to your maven project.properties at the top level of the 
-          project:
-        </p>
-        
-        <source>
-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
-        </source>
-        
-        <p>
-          The last property is a relative reference to the 
-          <b>sitedocs/src/etc/site.jsl</b> 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.
-        </p>
-      </subsection>
-      
-      <subsection name="project.xml">
-        <p>
-          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:
-        </p>
+      <table>
+        <tr>
+          <th>Topic</th>
+          <th>Description</th>
+        </tr>
+
+        <tr>
+          <td>
+            <a href="./maven-changes.html">Maven Changes</a>
+          </td>
+          <td>
+            Changes to the subproject's Maven configuration are needed.  This
+            document steps through making those changes.
+          </td>
+        </tr>
+        
+        <tr>
+          <td>
+            <a href="./hyperlink-management.html">Hyperlink Management</a>
+          </td>
+          <td>
+            Because a separate Maven site build is used to generate subproject
+            documentation and the generated documents are repositioned some
+            precautions must be taken to make hyperlinks and navigations work
+            properly.  This document explains the problem, and how to work 
+            around it for navigations and hyperlinks.
+          </td>
+        </tr>
+
+        <tr>
+          <td>
+            <a href="./sitedoc-deployment.html">Sitedoc Deployment</a>
+          </td>
+          <td>
+            When changes are made to sitedocs and subproject sitedocs developers
+            need to deploy those changes to the website.  This document 
+            describes the way incubator projects are setup and what the process
+            is for building and deploying the sitedocs for the TLP and 
+            subprojects.
+          </td>
+        </tr>
         
-        <source>
-&lt;name&gt;Apache Directory Project&lt;/name&gt;
-&lt;url&gt;http://incubator.apache.org/directory&lt;/url&gt;
-&lt;logo&gt;http://incubator.apache.org/directory/images/apache-directory-logo.png&lt;/logo&gt;
-
-&lt;organization&gt;
-  &lt;name&gt;Apache Incubator&lt;/name&gt;
-  &lt;url&gt;http://incubator.apache.org&lt;/url&gt;
-  &lt;logo&gt;http://incubator.apache.org/directory/images/apache-incubator-logo.png&lt;/logo&gt;
-&lt;/organization&gt;
-        </source>
-        
-        <p>
-          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:
-        </p>
-        
-        <img src="http://incubator.apache.org/directory/images/apache-directory-logo.png"/>
-        
-        <p>
-          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:
-        </p>
-        
-        <img src="http://incubator.apache.org/directory/images/apache-incubator-logo.png"/>
-      </subsection>
-      
-      <subsection name="Navigations">
-        <p>
-          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:
-        </p>
-        
-        <source>
-&lt;?xml version="1.0" encoding="UTF-8"?&gt;
-
-&lt;project&gt;
-
- &lt;title&gt;Apache Directory Project&lt;/title&gt;
-
- &lt;body&gt;
-
-    &lt;links&gt;
-      &lt;item name="Apache" href="http://apache.org/"/&gt;
-      &lt;item name="Directory" href="../../index.html"/&gt;
-      &lt;item name="Eve" href="/index.html"/&gt;
-      &lt;item name="LDAP" href="../ldap/index.html"/&gt;
-      &lt;item name="Naming" href="../naming/index.html"/&gt;
-      &lt;item name="Janus" href="../janus/index.html"/&gt;
-      &lt;item name="Snickers" href="../snickers/index.html"/&gt;
-      &lt;item name="Sitedocs" href="../sitedocs/index.html"/&gt;
-    &lt;/links&gt;
-
-    &lt;menu name="About Directory"&gt;
-      &lt;item name="Overview" href="../../index.html"/&gt;
-      &lt;item name="Community" href="../../community/index.html"/&gt;
-      &lt;item name="Latest News" href="../../news.html"/&gt;
-      &lt;item name="Subprojects" href="../../subprojects/index.html"&gt;
-        &lt;item name="Eve" href="/index.html"/&gt;
-        &lt;item name="LDAP" href="../ldap/index.html"/&gt;
-        &lt;item name="Janus" href="../janus/index.html"/&gt;
-        &lt;item name="Naming" href="../naming/index.html"/&gt;
-        &lt;item name="Snickers" href="../snickers/index.html"/&gt;
-        &lt;item name="Sitedocs" href="../sitedocs/index.html"/&gt;
-      &lt;/item&gt;
-      &lt;item name="Documentation" href="../../doc/index.html"/&gt;
-    &lt;/menu&gt;
-
-    &lt;menu name="Resources"&gt;
-      &lt;item name="IRC" href="../../irc.html"/&gt;
-      &lt;item name="Jira" href=
-        "http://nagoya.apache.org/jira/secure/BrowseProject.jspa?id=10400"/&gt;
-      &lt;item name="Wiki" href="http://wiki.apache.org/directory"/&gt;
-      &lt;item name="Lists" href="../../mailing-lists.html"/&gt;
-      &lt;item name="License" href="../../license.html"/&gt;
-      &lt;item name="Sandbox" href="../../sandbox/index.html"/&gt;
-      &lt;item name="Downloads" href="../../download.cgi"/&gt;
-      &lt;item name="Subversion" href="../../svn.html"/&gt;
-      &lt;item name="Related Projects" href="../../related/index.html"/&gt;
-    &lt;/menu&gt;
-
- &lt;/body&gt;
-
-&lt;/project&gt;
-        </source>
-        
-        <p>
-          You can download this navigation template from 
-          <a href="./nav-template.txt">here</a>.  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:
-        </p>
-        
-        <source>
-        &lt;item name="Eve" href="/index.html"&gt;
-          &lt;item name="Design" href="/design/index.html"/&gt;
-          &lt;item name="Features" href="/features.html"/&gt;
-          &lt;item name="Backend" href="/backend/index.html"/&gt;
-          &lt;item name="Frontend" href="/frontend/index.html"/&gt;
-        &lt;/item&gt;
-        </source>
-      </subsection>
-      
-      <subsection name="maven.xml">
-        <p>
-          Some scripting is required within the maven jelly scripting file for
-          your project.  As you may already know this maven.xml file sits at
-          your projects top level directory along side your project.xml file.
-          Here's what you have to add to it:
-        </p>
-        
-        <source>
-  &lt;postGoal name="site"&gt;
-    &lt;attainGoal name="subproject:collectdocs"/&gt;
-  &lt;/postGoal&gt;
-
-  &lt;goal name="subproject:collectdocs"&gt;
-    &lt;ant:copy toDir="../../../sitedocs/trunk/sitedocs/target/docs/subprojects/[subproject-name]"&gt;
-      &lt;ant:fileSet dir="${basedir}/target/docs"&gt;
-        &lt;ant:include name="**"/&gt;
-      &lt;/ant:fileSet&gt;
-    &lt;/ant:copy&gt;
-  &lt;/goal&gt;
-        </source>
-        
-        <p>
-          This Jelly code sets up a new goal to execute after the subproject's
-          site has been built.  It is called <em>subproject:collectdocs</em>.
-          Make sure you edit the toDir attribute value on the &lt;ant:copy&gt;
-          tag to use your subprojects destination directory.  It will copy the
-          generated output of your subproject site build under the sitedocs
-          directory in the respective position.
-        </p>
-      </subsection>
-
-      <subsection name="Links">
-        <p>
-          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 <b>subprojects/[supproject-name]</b> 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.
-        </p>
-        
-        <p>
-          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.
-        </p>
-      </subsection>
+      </table>
     </section>
-    
-    <section name="Deploying Site and Subprojects">
-      <subsection name="Incubator Site">
-        <p>
-          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.
-        </p>
-        
-        <p>
-          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 <b>incubator-directory</b> CVS
-          module.  I check it out like so:
-        </p>
-        
-        <source>
-cvs -d :ext:akarasulu@cvs.apache.org:/home/cvs co incubator-directory
-        </source>
-        
-        <p>
-          This module contains a content directory: <b>www</b>.  The final 
-          content under <b>www</b> is served up by the Apache servers.  The 
-          module's <b>www</b> folder is checked out daily into the following
-          directory on minotaur.apache.org: 
-          <b>/www/incubator.apache.org/directory</b>
-        </p>
-        
-        <p>
-          So all we have to do is generate the site out of our subversion 
-          working directory and copy the Maven generated content into the 
-          <b>www</b> folder of the CVS working copy for the incubator-directory
-          CVS module.  That's a mouth full.
-        </p>
-        
-        <p>
-          Once the generated content is copied, the changes are committed.  Then
-          deployers should ssh into minotaur and cd to the 
-          <b>/www/incubator.apache.org/directory</b> to do an update like so:
-        </p>
-        
-        <source>
-cd /www/incubator.apache.org/directory
-cvs update -d
-        </source>
-        
-        <p>
-          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.
-        </p>
-        
-      </subsection>
-      
-      <subsection name="Building Top Level Project Site">
-        <p>
-          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.
-        </p>
-        
-        <p>
-          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 <b>xdocs</b> folder.
-          Once the changes are made run:
-        </p>
-        
-        <source>
-maven site          
-        </source>
-        
-        <p>
-          This will generate the TLP site right under <b>target/docs</b>.  
-          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 <b>target/docs/subprojects/[subproject]</b> output

-          folder of the sitedocs module.
-        </p>
-        
-        <p>
-          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 <b>sitedocs/target/docs</b> folder.  
-        </p>
-        
-        <p>
-          The contents of the <b>sitedocs/target/docs</b> folder is what is
-          copied over into the <b>incubator-directory/www</b> folder and 
-          committed into CVS.
-        </p>
-      </subsection>
-    </section>
-
-    <section name="Maven Howto">
-      <p> 
-        Gotta add some of the logo stuff! And need to setup site.jsl.
-      </p>
-      
-      <p>
-        These settings must be preserved to keep the site consistant.
-      </p>
-    </section>
-
-    <section name="Navigation Howto">
-      <p>
-        Navigation hyperlinks follow the same rules that govern the way links 
-        are managed.  
-      </p>
-      <p>
-        Again these settings must be preserved to keep the site consistant.
-      </p>
-    </section>
-
   </body>
 </document>
  

Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/subprojects/sitedocs/maven-changes.xml
==============================================================================
--- (empty file)
+++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/subprojects/sitedocs/maven-changes.xml
Wed Feb  4 00:50:36 2004
@@ -0,0 +1,196 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<document>
+  <properties>
+    <author email="akarasulu@apache.org">Alex Karasulu</author>
+    <title>Apache Directory Project: </title>
+  </properties> 
+  
+  <body>
+    <section name="Overview">
+      <p>
+        This project documents what is to be the umbrella website for all
+        Directory Project Sub-Projects.  There are a few rules and information
+        that is needed by Sub-Project developers in order to integrate/plugin
+        their Sub-Project documentation with this website.  
+      </p> 
+      
+      <p>
+        We use maven and the xdoc format to manage site documents and site
+        generation.  The layout for the top level site is managed here in this
+        project.  This is a subproject area which is where subproject content
+        is deposited.  In case this does not happen correctly some stubs have 
+        been left in place of the subproject.  Here's where we keep subproject
+        xdoc stubs:
+      </p>
+      <source>
+sitedocs/xdocs/subprjects
+    ./eve
+    ./ldap     
+    ./janus
+    ./naming
+    ./snickers
+    ./sitedocs
+      </source>
+      
+      <p>
+        Obviously, rather than use stubs, the sitedocs subproject area will 
+        contain actual content which this page is part of.  These directories
+        as mentioned before contain stubs.  When the top level site is generated
+        the html created is deposited int the target/docs directory of the 
+        sitedocs project directory here: 
+      </p>
+      
+      <source>directory/sitedocs/trunk/sitedocs/target/docs</source>
+      
+      <p>
+        It is the reponsibility of subprojects to generate their own content 
+        and copy it over to their appropriate directory within the subprojects
+        directory.  The Eve subproject for example does this using a post goal
+        within the maven.xml project like so to copy its site documentation:
+      </p>
+      
+      <source>
+  &lt;postGoal name="site"&gt;
+    &lt;attainGoal name="server:copy-images"/&gt;
+    &lt;attainGoal name="subproject:collectdocs"/&gt;
+  &lt;/postGoal&gt;
+
+  &lt;goal name="subproject:collectdocs"&gt;
+    &lt;copy toDir="../../../sitedocs/trunk/sitedocs/target/docs/subprojects/eve"&gt;
+      &lt;fileSet dir="${basedir}/target/docs"&gt;
+        &lt;include name="**"/&gt;
+      &lt;/fileSet&gt;
+    &lt;/copy&gt;
+  &lt;/goal&gt;
+      </source>
+      
+      <p>
+        This however is not the only requirement.  As we'll see to maintain
+        consistancy throughout the site subproject documentation needs to 
+        manage links, manage the same navigations, set properties in maven 
+        and its pom.
+      </p>
+    </section>
+    
+    <section name="Subproject Integration Howto">
+      <p>
+        At the present time there are stubs that have been placed
+        into the respective directories for the subprojects.  So under <b>
+        sitedocs/xdocs/subprojects</b> where subproject directories are 
+        contained a stub <b><em>index.xml</em></b> and <b><em>navigation.xml
+        </em></b> will be found.
+      </p>
+      
+      <p>
+        We have done this to prevent users from encountering broken links on the
+        site.  Once you have built your subproject's site and are sure it works
+        remove the respective stubs for your subproject.  If you do not do so
+        your content may be over written by the stubs if someone deploys the
+        top level site without generating your subproject's content.  So please
+        rm these stubs from the repository once your subproject is up. 
+      </p>
+      
+      <p>
+        Below we point out all the files and changes that need to be made in
+        order to make your subproject integrate into the top level site to
+        maintain a consistant look and feel.
+      </p>
+      
+      <subsection name="project.properties">
+        <p>
+          Add this to your maven project.properties at the top level of the 
+          project:
+        </p>
+        
+        <source>
+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
+        </source>
+        
+        <p>
+          The last property is a relative reference to the 
+          <b>sitedocs/src/etc/site.jsl</b> 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.
+        </p>
+      </subsection>
+      
+      <subsection name="project.xml">
+        <p>
+          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:
+        </p>
+        
+        <source>
+&lt;name&gt;Apache Directory Project&lt;/name&gt;
+&lt;url&gt;http://incubator.apache.org/directory&lt;/url&gt;
+&lt;logo&gt;http://incubator.apache.org/directory/images/apache-directory-logo.png&lt;/logo&gt;
+
+&lt;organization&gt;
+  &lt;name&gt;Apache Incubator&lt;/name&gt;
+  &lt;url&gt;http://incubator.apache.org&lt;/url&gt;
+  &lt;logo&gt;http://incubator.apache.org/directory/images/apache-incubator-logo.png&lt;/logo&gt;
+&lt;/organization&gt;
+        </source>
+        
+        <p>
+          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:
+        </p>
+        
+        <img src="http://incubator.apache.org/directory/images/apache-directory-logo.png"/>
+        
+        <p>
+          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:
+        </p>
+        
+        <img src="http://incubator.apache.org/directory/images/apache-incubator-logo.png"/>
+      </subsection>
+      
+      <subsection name="maven.xml">
+        <p>
+          Some scripting is required within the maven jelly scripting file for
+          your project.  As you may already know this maven.xml file sits at
+          your projects top level directory along side your project.xml file.
+          Here's what you have to add to it:
+        </p>
+        
+        <source>
+  &lt;postGoal name="site"&gt;
+    &lt;attainGoal name="subproject:collectdocs"/&gt;
+  &lt;/postGoal&gt;
+
+  &lt;goal name="subproject:collectdocs"&gt;
+    &lt;ant:copy toDir="../../../sitedocs/trunk/sitedocs/target/docs/subprojects/[subproject-name]"&gt;
+      &lt;ant:fileSet dir="${basedir}/target/docs"&gt;
+        &lt;ant:include name="**"/&gt;
+      &lt;/ant:fileSet&gt;
+    &lt;/ant:copy&gt;
+  &lt;/goal&gt;
+        </source>
+        
+        <p>
+          This Jelly code sets up a new goal to execute after the subproject's
+          site has been built.  It is called <em>subproject:collectdocs</em>.
+          Make sure you edit the toDir attribute value on the &lt;ant:copy&gt;
+          tag to use your subprojects destination directory.  It will copy the
+          generated output of your subproject site build under the sitedocs
+          directory in the respective position.
+        </p>
+      </subsection>
+    </section>
+  </body>
+</document>

Modified: incubator/directory/sitedocs/trunk/sitedocs/xdocs/subprojects/sitedocs/navigation.xml
==============================================================================
--- incubator/directory/sitedocs/trunk/sitedocs/xdocs/subprojects/sitedocs/navigation.xml
(original)
+++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/subprojects/sitedocs/navigation.xml
Wed Feb  4 00:50:36 2004
@@ -27,7 +27,11 @@
         <item name="Janus" href="/subprojects/janus/index.html"/>
         <item name="Naming" href="/subprojects/naming/index.html"/>
         <item name="Snickers" href="/subprojects/snickers/index.html"/>
-        <item name="Sitedocs" href="/subprojects/sitedocs/index.html"/>
+        <item name="Sitedocs" href="/subprojects/sitedocs/index.html">
+          <item name="Maven Changes" href="/subprojects/sitedocs/maven-changes.html"/>
+          <item name="Hyperlink Management" href="/subprojects/sitedocs/hyperlink-management.html"/>
+          <item name="Sitedoc Deployment" href="/subprojects/sitedocs/sitedoc-deployment.html"/>
+        </item>
       </item>
       <item name="Documentation" href="/doc/index.html"/>
     </menu>

Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/subprojects/sitedocs/sitedoc-deployment.xml
==============================================================================
--- (empty file)
+++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/subprojects/sitedocs/sitedoc-deployment.xml
Wed Feb  4 00:50:36 2004
@@ -0,0 +1,109 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<document>
+  <properties>
+    <author email="akarasulu@apache.org">Alex Karasulu</author>
+    <title>Apache Directory Project: </title>
+  </properties> 
+  
+  <body>
+    <section name="Deploying Site and Subprojects">
+      <subsection name="Incubator Site">
+        <p>
+          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.
+        </p>
+        
+        <p>
+          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 <b>incubator-directory</b> CVS
+          module.  I check it out like so:
+        </p>
+        
+        <source>
+cvs -d :ext:akarasulu@cvs.apache.org:/home/cvs co incubator-directory
+        </source>
+        
+        <p>
+          This module contains a content directory: <b>www</b>.  The final 
+          content under <b>www</b> is served up by the Apache servers.  The 
+          module's <b>www</b> folder is checked out daily into the following
+          directory on minotaur.apache.org: 
+          <b>/www/incubator.apache.org/directory</b>
+        </p>
+        
+        <p>
+          So all we have to do is generate the site out of our subversion 
+          working directory and copy the Maven generated content into the 
+          <b>www</b> folder of the CVS working copy for the incubator-directory
+          CVS module.  That's a mouth full.
+        </p>
+        
+        <p>
+          Once the generated content is copied, the changes are committed.  Then
+          deployers should ssh into minotaur and cd to the 
+          <b>/www/incubator.apache.org/directory</b> to do an update like so:
+        </p>
+        
+        <source>
+cd /www/incubator.apache.org/directory
+cvs update -d
+        </source>
+        
+        <p>
+          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.
+        </p>
+        
+      </subsection>
+      
+      <subsection name="Building Top Level Project Site">
+        <p>
+          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.
+        </p>
+        
+        <p>
+          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 <b>xdocs</b> folder.
+          Once the changes are made run:
+        </p>
+        
+        <source>
+maven site          
+        </source>
+        
+        <p>
+          This will generate the TLP site right under <b>target/docs</b>.  
+          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 <b>target/docs/subprojects/[subproject]</b> output

+          folder of the sitedocs module.
+        </p>
+        
+        <p>
+          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 <b>sitedocs/target/docs</b> folder.  
+        </p>
+        
+        <p>
+          The contents of the <b>sitedocs/target/docs</b> folder is what is
+          copied over into the <b>incubator-directory/www</b> folder and 
+          committed into CVS.
+        </p>
+      </subsection>
+    </section>
+  </body>
+</document>

Mime
View raw message