You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by ak...@apache.org on 2004/02/04 09:50:37 UTC
svn commit: rev 6497 - incubator/directory/sitedocs/trunk/sitedocs/xdocs/subprojects/sitedocs
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>
+<?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>
+ </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>
+ <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>
+ </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>
- <postGoal name="site">
- <attainGoal name="server:copy-images"/>
- <attainGoal name="subproject:collectdocs"/>
- </postGoal>
-
- <goal name="subproject:collectdocs">
- <copy toDir="../../../sitedocs/trunk/sitedocs/target/docs/subprojects/eve">
- <fileSet dir="${basedir}/target/docs">
- <include name="**"/>
- </fileSet>
- </copy>
- </goal>
- </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>
-<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>
- </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>
-<?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>
- </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>
- <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>
- </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>
- <postGoal name="site">
- <attainGoal name="subproject:collectdocs"/>
- </postGoal>
-
- <goal name="subproject:collectdocs">
- <ant:copy toDir="../../../sitedocs/trunk/sitedocs/target/docs/subprojects/[subproject-name]">
- <ant:fileSet dir="${basedir}/target/docs">
- <ant:include name="**"/>
- </ant:fileSet>
- </ant:copy>
- </goal>
- </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 <ant:copy>
- 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>
+ <postGoal name="site">
+ <attainGoal name="server:copy-images"/>
+ <attainGoal name="subproject:collectdocs"/>
+ </postGoal>
+
+ <goal name="subproject:collectdocs">
+ <copy toDir="../../../sitedocs/trunk/sitedocs/target/docs/subprojects/eve">
+ <fileSet dir="${basedir}/target/docs">
+ <include name="**"/>
+ </fileSet>
+ </copy>
+ </goal>
+ </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>
+<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>
+ </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>
+ <postGoal name="site">
+ <attainGoal name="subproject:collectdocs"/>
+ </postGoal>
+
+ <goal name="subproject:collectdocs">
+ <ant:copy toDir="../../../sitedocs/trunk/sitedocs/target/docs/subprojects/[subproject-name]">
+ <ant:fileSet dir="${basedir}/target/docs">
+ <ant:include name="**"/>
+ </ant:fileSet>
+ </ant:copy>
+ </goal>
+ </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 <ant:copy>
+ 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>