[prev in list] [next in list] [prev in thread] [next in thread]
List: forrest-dev
Subject: [patch] forrestbot: project/@sendon, draft docs
From: "Marc Portier" <mpo () outerthought ! org>
Date: 2002-07-31 8:25:52
[Download RAW message or body]
Hi there,
since I don't have the rights yet (summer recess?), maybe someone can apply
this new patch once again
this is adding support for the optional @sendon attribute on the <project>
elm
of the forrestbot.conf.xml.
- sendon="error" will make the naggmail only be sent in case of failure,
and is the new default
- sendon="always" will make the mail be sent in both success and fail
cases
(this was the de facto default up to now)
while patching this I pushed the mail task to become a template (see
templates.build.xml) and I changed the propertyname for mailhost to
mail.host (just fits in better like this)
moving it to the templates will ensure that we don't need to play around in
the xsl anymore for changes to how it works/what it does.
I also have some documentation ready, maybe some can give their opinion on
the first drafts of the 'forrestbot-explained' and 'thecontract'
(cvs diff -u -N didn't add them since I couldn't cvs add them to the
anonymous repository of course, so just slide them in somewhere if you like
them)
have fun,
-marc=
--
Marc Portier http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
mpo@outerthought.org info@outerthought.org
["forrestbot-explained.xml" (text/xml)]
<?xml version="1.0"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
<header>
<title>ForrestBot Manual</title>
<authors><person name="Marc Portier"
email="mpo@outerthought.org"/></authors>
<abstract>This document explains how the forrest project can be used to
centrally build the HTML documentation for different projects.<br/>It also
explains which pieces in the forrest distribution come to play to achieve this
functionality, and how they could be extended in the future.</abstract>
</header>
<body>
<note>Related to this document it might be useful to check the
<link>contract</link> that explains which rules your project should comply to
when you want it to make use of forrest.</note>
<section>
<title>Using the Forrest Robot</title>
<section>
<title>Setting up the centralized service.</title>
<p>Historically the robot has been thought of as a script that
regularly is executed. The goal being to publish a purely static website that
near-real-time-like updates to newly available content. </p>
<p>Running the robot is as easy as calling the following in your shell.
(executed in the root dir of the distribution.)</p>
<source>build bot -Dbot.forrestbot.xconf=myOwn.conf.xml -Dtemplate.echo=[true|false]</source>
<p>It is quite typical to perform this from a shell script that gets
scheduled for execution on a regular basis. </p>
<p>The actions the robot is going to take are written down in the XML
file pointed at with the 'bot.forrestbot.xconf' System property. (if not
specified with <code>-Dbot.forrest.xconf </code>the default config from the
distribution is taken: ./forrestbot.conf.xml) </p>
</section>
<section>
<title>Describing your project to the robot.</title>
<fixme author="mpo">There is not yet a DTD for this configuration
file.</fixme>
<p>The robot's work is written down in an XML configuration file, which
has one (optional) child-element for setting cross-project defaults followed by
a list of project-elements that hold the configuration for the various projects
the robot is going to work on. </p>
<source><![CDATA[<?xml version="1.0" encoding="ISO-8859-1"?>
<forrest-config>
<defaults>
...<!-- different fallback values for various workstages -->
</defaults>
<project name="project-name-1">
...<!-- different subelements configure the various workstages -->
</project>
<project name="project-name-2">
...<!-- different subelements configure the various workstages -->
</project>
</forrest-config>
]]></source>
<p>During the robot-run, each project entry will start a parallel and
independent process consisting of a number of so called 'workstages'.</p>
<p>These workstages are listed in the
<code>./src/resources/forrestbot/stages.conf.xml</code> file and their actual
execution is handled by the various template tasks in the
<code>./resources/forrestbot/ant/</code>templates.build.xml file. </p>
<p>Currently the various workstages are:</p>
<ul>
<dl>
<dt>prepare</dt>
<dd> Make a clean forrest-defined cocoon context environment.</dd>
</dl>
<dl>
<dt>get-src</dt>
<dd>Slide in the project specific document sources in that cocoon
context environment.</dd>
</dl>
<dl>
<dt>generate</dt>
<dd> Actually generate the site using Cocoon</dd>
</dl>
<dl>
<dt>deploy</dt>
<dd>Publish the newly created site</dd>
</dl>
<dl>
<dt>cleanup</dt>
<dd><No real actions yet></dd>
</dl>
</ul>
<p>Inside the project element the configuration allows to set some
parameters that get consumed in the template targets. This workstage dependant
configuration always takes up the following layout: an element with the name of
one of the tasks, and an optional type-attribute with nested elements that hold
parameter names, with required name attribute holding the actual parameter
value. Example:</p>
<source>
<project name="xml-forrest">
<prepare>
<skin name="bert"/>
</prepare>
<get-src type="cvs">
<host name="cvs.apache.org"/>
<root name="/home/cvspublic"/>
<user name="anoncvs"/>
<passwd name="anoncvs"/>
<module name="xml-forrest"/>
<dir name="src/documentation"/>
</get-src>
<generate>
<debuglevel name="ERROR" />
</generate>
<deploy type="scp">
<host name="krysalis.sourceforge.net"/>
<root name="/home/groups/k/kr/krysalis/htdocs"/>
<user name="forrestbot"/>
<dir name="forrest"/>
</deploy>
</project>
</source>
<note>Only the workstages that need configuration settings have an
entry here. At all times there will be a workstage template called for each
stage of the stages.conf.xml (even if it is not explicitly mentioned inside the
<project> element.) </note>
<p>Explained in detail, this will</p>
<ul>
<li>SET names properties (workstage(.@type)?.*) to appropriate values
(*/@name)</li>
<ul>
<dl>
<dt>prepare.skin</dt>
<dd>bert</dd>
</dl>
<dl>
<dt>get.cvs.host</dt>
<dd>cvs.apache.org</dd>
</dl>
<dl>
<dt>get.cvs.root</dt>
<dd>/home/cvspublic</dd>
</dl>
<dl>
<dt>get.cvs.user</dt>
<dd>anoncvs</dd>
</dl>
<dl>
<dt>passwd</dt>
<dd>anoncvs</dd>
</dl>
<dl>
<dt>get.cvs.module</dt>
<dd>xml-forrest</dd>
</dl>
<dl>
<dt>get.cvs.dir</dt>
<dd>src/documentation</dd>
</dl>
<dl>
<dt>generate.debuglevel</dt>
<dd>ERROR</dd>
</dl>
<dl>
<dt>deploy.scp.host</dt>
<dd>krysalis.sourceforge.net</dd>
</dl>
<dl>
<dt>deploy.scp.root</dt>
<dd>/home/groups/k/kr/krysalis/htdocs</dd>
</dl>
<dl>
<dt>deploy.scp.user</dt>
<dd>forrestbot</dd>
</dl>
<dl>
<dt>deploy.scp.dir</dt>
<dd>forrest</dd>
</dl>
</ul>
<li>and CALL the following templates
(template.workstage(.@type)?):</li>
<ul>
<li>template.prepare</li>
<li>template.get-src.cvs</li>
<li>template.generate</li>
<li>template.deploy.scp</li>
<li>template.cleanup</li>
</ul>
</ul>
<p>What each of these templates is going to do with the parameters can
be found in the templates.build.xml itself (at this stage) and is put out to
the console if the bot is ran with the <code>-Dtemplate.echo=true</code>
flag</p>
<section>
<title>Setting robot-wide defaults.</title>
<p>The <code><defaults> </code>section in the
<code><forrest-config></code> allows for one-time setting of parameters
you want to reuse for different projects. The syntax (and semantic value) of
the nested elements is identical to the use inside the
<code><project></code> tags.</p>
</section>
</section>
<note>Once you understand all of this you might decide NOT to run your
own centralized service but rather ask your project to be taken up in the
centralized service of the project team itself: just send a mail to
forrest-dev@apache.org listing the required parameters to be taken up in the
process.</note>
<section>
<title>Checking logs and getting them by mail.</title>
<p>For each distinct project the forrest robot is maintaining a
separate working log of the different workstages being executed. These logs can
be opened and viewed in the ./build/bot directory</p>
<p>In addition to the @name attribute the <project> tag also can
contain a @sendlogto attribute that must be holding a (comma separated list
off) email address(es) where the project specific log needs to be sent to after
all workstages have been completed (or as soon as building failed)</p>
</section>
</section>
<section>
<title>ForrestBot design.</title>
<p>Most of us will just like things to work, and will be happy enough
just using it, maybe even letting <link
href="mailto:forrest-dev@apache.org">us</link> know if we could improve this or
the other. Some however might be drawn to the <link>how stuff works</link> of
things. For them is this section as a start in the rest of their own
pursuit.</p>
<section>
<title>The ant play.</title>
<p>All actions and targets related to the actual execution of the
robot's work is separated over 3 distinct build files:</p>
<ul>
<dl>
<dt>[main] <code>./build.xml</code></dt>
<dd>the starting point where generation and preparation is initiated.
</dd>
</dl>
<dl>
<dt>[generated] <code>./build/bot/work.build.xml</code></dt>
<dd>the one that reflects the configured tasks in the
forrestbot.conf.xml</dd>
</dl>
<dl>
<dt>[templates]
<code>./src/resources/forrestbot/ant/templates.build.xml</code></dt>
<dd>listing the different targets that actually depict the supported
workstages (and types of)</dd>
</dl>
</ul>
<p>The complete process runs as follows:</p>
<ol>
<li>'bot' target inside main build.xml depends on a number of targets
that</li>
<ol>
<li>'bot.init': initialize the environment</li>
<li>'bot.conf2build': use XSLT stylesheets to convert the
forrestbot.conf.xml into the work.build.xml (and a properties file for the
default-section)</li>
<li>'bot.run': delegates to the 'work' target of the generated
work.build.xml</li>
</ol>
<li>'work' target inside generated work.build.xml will then start in
parallel (so failure of the one would not influence the other) the different
project specific work-processes. </li>
<li>each of these project runs (generated 'work.[projectname]' targets)
depends on the sequential execution of the different workstage actions
(generated '[workstage].[projectname(.[type])?]' targets) </li>
<li>In those specific targets the pattern is as follows:</li>
<ol>
<li>set the project specific parameters for this project and
workstage</li>
<li>load the default parameter values for the ones that aren't set
yet</li>
<li>call the actual template.[workstage(.[type]?)]</li>
</ol>
</ol>
</section>
<section>
<title>Adding features to the robot - The meta template</title>
<p>Given the mechanism, the actual things the robot _can_ do boil down
to the template targets it can call. So extending the robot means: adding
templates-targets.</p>
<p>Could be silly to you, but there is this bit of a way of working to
keep the <code>template.build.xml</code> file a bit readable. So please fit
in:</p>
<ul>
<li> in the future there will be a DTD for forrestbot.conf.xml that
should be updated probably after you added stuff to the
<code>templates.build.xml</code>.</li>
<li>build an echo target for each template target you make: </li>
</ul>
<source><![CDATA[
<target name="echo.workstage-name.optional-type" if="template.echo">
... here you put echo ant-tasks that somewhat tell what you will
... do with all the params you expect
</target>
<target name="template.workstage-name.optional-type"
depends="shared.set-props, echo.workstage-name.optional-type">
... here you put whatever ant-tasks that actually do it
</target>
]]></source>
</section>
</section>
</body>
</document>
["thecontract.xml" (text/xml)]
<?xml version="1.0"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
<header>
<title>The Contract</title><authors><person name="Marc Portier"
email="mpo@outerthought.org"/></authors>
<abstract>This document describes the formal contract between the
<strong>Forrest distribution code</strong>, hereafter referred as Forrest,
<br/>and the <strong>Project (team) using it for generating its documentation
web-site</strong>, hereafter TheProject, or in the best case: You. </abstract>
</header>
<body>
<warning>The legal tone of voice is just a gimmick, this is not a legal
document in any sense.<br/>At all times: since this is open source: the real
contract is described in the implementation details of the full distribution.
This tries to list (not explain) what the ins and outs of using forrest is
about. Please let <link href="mailto:forrest-dev@apache.org">us</link> know if
any of the bullets listed here are out of sync with the real
implementation.</warning>
<section>
<title>Forrest will:</title>
<ul>
<li>provide DTD's, skins, cocoon-pipelines, and a willing team of
supporting developers at <link
href="mailto:forrest-dev@apache.org">forrest-dev@apache.org</link></li>
<li>use cocoon to generate the HTML documentation for TheProject</li>
</ul>
</section>
<section>
<title>TheProject Must:</title>
<ul>
<li>provide xml content in ./content/xdocs using the forrest DTD's</li>
<li>provide content navigation metadata by sliding book.xml files in
there as well. (Forrest is working on the libre alternative to the book.xml
approach)</li>
</ul>
</section>
<section>
<title>TheProject Can (accidentally):</title>
<warning>Use the following features at own risk. These are a side-effects
of the current way of building the documentation of TheProject. It is expected
that there will be more thought of ways to actually do this then the current
style being: files from TheProject will overwrite the originals of
Forrest.</warning>
<ul>
<li>provide his own skin in a directory ./skins/mySkin (check the
forrest skins and the related pipelines to see what they are doing)</li>
<li>provide own dtd's (and stylesheets) to work with in
./resources/schema/dtd
<ul>
<li>maybe also extra required stylesheets to convert own grammar to
'document' (being the format that the skins work on)</li>
<li>and probably with an updated ./resources/schema/catalog</li>
</ul> </li>
<li>provide his own overwriting versions of ./sitemap.xmap,
./cocoon.xconf etc etc (be sure you know what you are doing since you're
leaving the area where other Forresters can help you out.</li>
</ul>
</section>
<section>
<title>TheProject Cannot (currently)</title>
<p>For a lot of the following we're still looking for the actual use
cases.</p>
<ul>
<li>provide own Java classes or libraries needed in the generation
process.</li>
<li>provide mountable sub-sitemaps.</li>
</ul>
</section>
</body>
</document>
["20020731.forrestdiff.txt" (text/plain)]
? 20020731.forrestdiff.txt
? ant-mail.properties
? testbot.conf.xml
? src/documentation/content/xdocs/forrestbot-explained.xml
? src/documentation/content/xdocs/thecontract.xml
? src/resources/schema/dtd/document-v11.css
? src/resources/schema/dtd/document-v11.ctm
? src/resources/schema/dtd/document-v11.rlx
? src/resources/schema/dtd/document-v11.tbr
Index: src/resources/forrestbot/ant/templates.build.xml
===================================================================
RCS file: /home/cvspublic/xml-forrest/src/resources/forrestbot/ant/templates.build.xml,v
retrieving revision 1.6
diff -u -r1.6 templates.build.xml
--- src/resources/forrestbot/ant/templates.build.xml 27 Jul 2002 06:01:46 -0000 1.6
+++ src/resources/forrestbot/ant/templates.build.xml 31 Jul 2002 08:09:07 -0000
@@ -331,10 +331,10 @@
<!-- [[deploy type ftp ]] -->
<target name="echo.deploy.ftp" if="template.echo">
<echo>
- deploy workstage of type ftp for project ${project.name}
- will use ftp to host: ${deploy.ftp.host}
- impersonating user: ${deploy.ftp.user} with passwd: ${deploy.ftp.passwd}
- to copy the stuff to relative user dir: ${deploy.ftp.destination}
+Deploy workstage of type ftp for project ${project.name}
+Will use ftp to host: ${deploy.ftp.host}
+Impersonating user: ${deploy.ftp.user} with passwd: ${deploy.ftp.passwd}
+to copy the stuff to relative user dir: ${deploy.ftp.destination}
</echo>
</target>
@@ -358,6 +358,36 @@
</target>
<target name="template.cleanup" depends="shared.set-props, echo.cleanup">
<!-- todo: FIXME: not implemented yet -->
+ </target>
+
+
+
+ <!-- ________________ MAIL TEMPLATE ______________________ -->
+ <target name="echo.mail" if="template.echo">
+ <echo>
+Will send mail (${mail.send}) to ${mail.to} about the completion-status \
${mail.completion-status} +of the work the robot has done on project ${project.name}.
+The mail will hold the attachment(s) ${mail.attachments}
+[using smtp host: ${mail.host}]
+ </echo>
+ </target>
+
+ <target name="template.mail" if="mail.send" depends="echo.mail">
+ <property name="mail.host" value="localhost" />
+ <mail from="forrest-bot@xml.apache.org"
+ mailhost="${mail.host}"
+ tolist="${mail.to}"
+ subject="[DO NOT REPLY] ForrestBot site builder for '${project.name}'"
+ files="${mail.attachments}"
+ failonerror="false">
+ <message>
+Another hard day at the BOT factory, and quite happy to have worked for you.
+Our completion status for your project ${project.name} was ${mail.completion-status}
+Please find the details in the log attached.
+
+The Forrest-Bot team. (http://xml.apache.org/forrest)
+ </message>
+ </mail>
</target>
</project>
Index: src/resources/forrestbot/xslt/config2work.xsl
===================================================================
RCS file: /home/cvspublic/xml-forrest/src/resources/forrestbot/xslt/config2work.xsl,v
retrieving revision 1.4
diff -u -r1.4 config2work.xsl
--- src/resources/forrestbot/xslt/config2work.xsl 27 Jul 2002 06:01:47 -0000 1.4
+++ src/resources/forrestbot/xslt/config2work.xsl 31 Jul 2002 08:09:07 -0000
@@ -54,30 +54,27 @@
<try>
<ant antfile="${{bot.work.build.xml}}" inheritRefs="true"
target="work.{@name}" \
output="${{bot.build.dir}}/work.{@name}.log"/>
- <property name="completion-status.{@name}" value="SUCCESS" />
+ <property name="mail.completion-status" value="SUCCESS" />
</try>
<catch>
<echo message="Failed to complete workstages for project {@name}" />
- <property name="completion-status.{@name}" value="FAIL" />
+ <property name="mail.completion-status" value="FAIL" />
</catch>
- <finally>
- <xsl:if test="@sendlogto">
- <mail from="forrest-bot@xml.apache.org"
- mailhost="${{mailhost}}"
- tolist="{@sendlogto}"
- subject="[DO NOT REPLY] ForrestBot site builder for '{@name}'"
- files="${{bot.build.dir}}/work.{@name}.log"
- failonerror="false">
- <message>
-Another hard day at the BOT factory, and quite happy to have worked for you.
-Our completion status for your project [<xsl:value-of select="@name" />] was \
${completion-status.<xsl:value-of select="@name"/>}
-Please find the details in the log attached.
-
-The Forrest-Bot team. (http://xml.apache.org/forrest)
- </message>
- </mail>
- </xsl:if>
- </finally>
+ <xsl:if test="@sendlogto">
+ <finally>
+ <property name="mail.to" value="{@sendlogto}" />
+ <property name="mail.attachments" value="${{bot.build.dir}}/work.{@name}.log" \
/> + <condition property="mail.send">
+ <or>
+ <equals arg1="${{mail.completion-status}}" arg2="error" />
+ <equals arg1="{@sendon}" arg2="always" />
+ </or>
+ </condition>
+ <ant antfile="${{bot.templates.build.xml}}" target="template.mail" \
inheritRefs="true"> + <property name="project.name" value="{@name}" />
+ </ant>
+ </finally>
+ </xsl:if>
</antipede-trycatch>
</xsl:for-each>
</parallel>
@@ -186,3 +183,8 @@
</xsl:template>
</xsl:stylesheet>
+<!-- Stylus Studio meta-information - (c)1998-2002 eXcelon Corp.
+<metaInformation>
+<scenarios ><scenario default="yes" name="test" userelativepaths="yes" \
externalpreview="no" url="..\..\..\..\testbot.conf.xml" htmlbaseurl="" \
processortype="xalan" commandline="" additionalpath="" additionalclasspath="" \
postprocessortype="none" postprocesscommandline="" postprocessadditionalpath="" \
postprocessgeneratedext=""/></scenarios><MapperInfo srcSchemaPath="" srcSchemaRoot="" \
srcSchemaPathIsRelative="yes" srcSchemaInterpretAsXML="no" destSchemaPath="" \
destSchemaRoot="" destSchemaPathIsRelative="yes" destSchemaInterpretAsXML="no"/> \
+</metaInformation> +-->
\ No newline at end of file
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic