site/src/site/xdoc/projects/sitedocs/maven-changes.xml - directory-project - Git at Google

 <?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
     ./server
     ./ldap
     ./authx
     ./naming
     ./asn1
     ./kerberos
     ./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>
	<?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
	./server
	./ldap
	./authx
	./naming
	./asn1
	./kerberos
	./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>