src/documentation/content/xdocs/forrestbot-intro-old.xml - forrest - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!--
   Copyright 2002-2004 The Apache Software Foundation

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
 -->
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://apache.org/forrest/dtd/document-v12.dtd">

 <document>
  <header>
   <title>Forrestbot introduction</title>
   <subtitle>Getting started with using Forrestbot</subtitle>
   <version>0.2</version>
  </header>

  <body>
  <warning>This documentation applies to the forrestbot included with Forrest 0.5.1 or previous releases.
   The next version of forrest will include a new forrestbot, which has some documentation <link href="site:forrestbot">here</link>.
  </warning>
  <section>
   <title>Goal</title>
   <p>
    You have your own project and you want to use Forrest to build the project
    documentation.
   </p>
  </section>

  <section>
   <title>Introduction</title>
   <p>
    The <strong>ForrestBot</strong> will automatically build and publish your
    documentation on a regular basis. The versatile ForrestBot can retrieve
    source XML instances from various type of repository (e.g. local filesystem,
    local CVS, remote CVS), generate the documents, and copy the result to a
    local or remote location (optionally via secure methods). It can be run
    from the command-line as part of your documentation edit-build-review cycle,
    it can be called from cron to automate your website update, it can operate
    as a centralised docs-build service for a set of remote projects, it can do
    tasks in parallel, and do even more.
    See some websites that are automatically built with ForrestBot at
    <link href="http://forrestbot.cocoondev.org/">http://forrestbot.cocoondev.org/</link>
   </p>
   <p>
    This document provides a concise overview of one particular scenario. See
    <link href="site:forrestbot">The ForrestBot</link> for details and understand
    <link href="site:forrest-contract">Our Contract</link>.
    We assume that you have built and configured Forrest as described in
    <link href="your-project.html">Using Forrest</link>.
   </p>
   <p>
    Please send your feedback to <code>forrest-dev</code> - the ForrestBot
    will be enhanced to meet diverse needs.
   </p>
   <p>
    (Building the documentation for the actual Forrest project is a separate
    issue. Use
    <code>./build.sh site</code> ... that will provide overview
    documentation about how Forrest operates and how you can help to improve it.)
   </p>
  </section>

  <section>
   <title>Establish project source directory</title>
   <p>The directory that contains your XML instances.</p>
   <ul>
    <li><code>PROJECT_HOME = /home/you/yourproject</code></li>
    <li><code>SRC_DOC = $PROJECT_HOME/src/documentation</code></li>
   </ul>
   <p>
    Your XML instance documents are at <code>$SRC_DOC/content/xdocs</code>
   </p>
  </section>

  <section>
   <title>Establish project configuration</title>
   <p>See the sample configurations at
    <code>xml-forrest/src/resources/forrestbot/samples/</code>
    copy one and edit it to replace the <code><![CDATA[<project>]]></code>
    definitions with our own, i.e.
   </p>
 <source><![CDATA[
   <project name="yourProject-local">
     <prepare>
         <skin name="forrest-site"/>
     </prepare>
     <get-src type="local-copy">
       <project-dir name="/home/you/yourproject" />
       <content-dir name="/home/you/yourproject/src/documentation"/>
     </get-src>
     <deploy type="local-copy">
       <destination name="/var/www/html/yourproject"/>
     </deploy>
   </project>
 ]]></source>
  </section>

  <section>
   <title>Run ForrestBot</title>
 <source><![CDATA[
 [you@locahost]$ cd $PROJECT_HOME
 [you@locahost]$ forrestbot -Dbot.config=<name>
 ... where <name> is the pathname to your configuration file.
 ]]></source>
   <p>There are also convenience scripts for automation.
    See
    <code>xml-forrest/src/resources/forrestbot/scripts/README.txt</code>
   </p>
  </section>

  <section>
   <title>Next Steps</title>
   <p>Some enhancements to your ForrestBot would be ...</p>
   <ul>
    <li>Add your own skin as described in
    <link href="your-project.html">Using Forrest</link>.
    </li>
    <li>Configure another <code><![CDATA[<project>]]></code> to conduct a secure
      copy to your public website.
    </li>
    <li>Instruct ForrestBot to send you email about the activities.
    </li>
    <li>Manage your XML instances with CVS and instruct ForrestBot to get
      the source.
    </li>
    <li>Use the "Forrestbot web interface" (website staging application).
    <code>xml-forrest/src/resources/forrestbot/webapp/WEB-INF/README.txt</code>
    </li>
   </ul>
  </section>

  <section>
   <title>Other methods</title>
   <p>See the <link href="site:your-project">Using Forrest</link> document.</p>
   <p>Forrest can also run as a dynamic webapp.</p>
  </section>

  </body>
 </document>
	<?xml version="1.0" encoding="UTF-8"?>
	<!--
	Copyright 2002-2004 The Apache Software Foundation

	Licensed under the Apache License, Version 2.0 (the "License");
	you may not use this file except in compliance with the License.
	You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->
	<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://apache.org/forrest/dtd/document-v12.dtd">

	<document>
	<header>
	<title>Forrestbot introduction</title>
	<subtitle>Getting started with using Forrestbot</subtitle>
	<version>0.2</version>
	</header>

	<body>
	<warning>This documentation applies to the forrestbot included with Forrest 0.5.1 or previous releases.
	The next version of forrest will include a new forrestbot, which has some documentation <link href="site:forrestbot">here</link>.
	</warning>
	<section>
	<title>Goal</title>
	<p>
	You have your own project and you want to use Forrest to build the project
	documentation.
	</p>
	</section>

	<section>
	<title>Introduction</title>
	<p>
	The <strong>ForrestBot</strong> will automatically build and publish your
	documentation on a regular basis. The versatile ForrestBot can retrieve
	source XML instances from various type of repository (e.g. local filesystem,
	local CVS, remote CVS), generate the documents, and copy the result to a
	local or remote location (optionally via secure methods). It can be run
	from the command-line as part of your documentation edit-build-review cycle,
	it can be called from cron to automate your website update, it can operate
	as a centralised docs-build service for a set of remote projects, it can do
	tasks in parallel, and do even more.
	See some websites that are automatically built with ForrestBot at
	<link href="http://forrestbot.cocoondev.org/">http://forrestbot.cocoondev.org/</link>
	</p>
	<p>
	This document provides a concise overview of one particular scenario. See
	<link href="site:forrestbot">The ForrestBot</link> for details and understand
	<link href="site:forrest-contract">Our Contract</link>.
	We assume that you have built and configured Forrest as described in
	<link href="your-project.html">Using Forrest</link>.
	</p>
	<p>
	Please send your feedback to <code>forrest-dev</code> - the ForrestBot
	will be enhanced to meet diverse needs.
	</p>
	<p>
	(Building the documentation for the actual Forrest project is a separate
	issue. Use
	<code>./build.sh site</code> ... that will provide overview
	documentation about how Forrest operates and how you can help to improve it.)
	</p>
	</section>

	<section>
	<title>Establish project source directory</title>
	<p>The directory that contains your XML instances.</p>
	<ul>
	<li><code>PROJECT_HOME = /home/you/yourproject</code></li>
	<li><code>SRC_DOC = $PROJECT_HOME/src/documentation</code></li>
	</ul>
	<p>
	Your XML instance documents are at <code>$SRC_DOC/content/xdocs</code>
	</p>
	</section>

	<section>
	<title>Establish project configuration</title>
	<p>See the sample configurations at
	<code>xml-forrest/src/resources/forrestbot/samples/</code>
	copy one and edit it to replace the <code><![CDATA[<project>]]></code>
	definitions with our own, i.e.
	</p>
	<source><![CDATA[
	<project name="yourProject-local">
	<prepare>
	<skin name="forrest-site"/>
	</prepare>
	<get-src type="local-copy">
	<project-dir name="/home/you/yourproject" />
	<content-dir name="/home/you/yourproject/src/documentation"/>
	</get-src>
	<deploy type="local-copy">
	<destination name="/var/www/html/yourproject"/>
	</deploy>
	</project>
	]]></source>
	</section>

	<section>
	<title>Run ForrestBot</title>
	<source><![CDATA[
	[you@locahost]$ cd $PROJECT_HOME
	[you@locahost]$ forrestbot -Dbot.config=<name>
	... where <name> is the pathname to your configuration file.
	]]></source>
	<p>There are also convenience scripts for automation.
	See
	<code>xml-forrest/src/resources/forrestbot/scripts/README.txt</code>
	</p>
	</section>

	<section>
	<title>Next Steps</title>
	<p>Some enhancements to your ForrestBot would be ...</p>
	<ul>
	<li>Add your own skin as described in
	<link href="your-project.html">Using Forrest</link>.
	</li>
	<li>Configure another <code><![CDATA[<project>]]></code> to conduct a secure
	copy to your public website.
	</li>
	<li>Instruct ForrestBot to send you email about the activities.
	</li>
	<li>Manage your XML instances with CVS and instruct ForrestBot to get
	the source.
	</li>
	<li>Use the "Forrestbot web interface" (website staging application).
	<code>xml-forrest/src/resources/forrestbot/webapp/WEB-INF/README.txt</code>
	</li>
	</ul>
	</section>

	<section>
	<title>Other methods</title>
	<p>See the <link href="site:your-project">Using Forrest</link> document.</p>
	<p>Forrest can also run as a dynamic webapp.</p>
	</section>

	</body>
	</document>