Phing rST task has landed

A while ago I began to write documentation for SemanticScuttle in rST (reStructuredText) format. When deploying new versions, the .rst files need to be converted to HTML and will get packaged up with the release.

SemanticScuttle uses Phing for deployment, which is a great time saver and packaging bug preventer.

Since Phing itself didn't contain a task to render rST files, I had to use the foreach and exec task:

  <target name="build-docs">
   <foreach param="fname" absparam="abs-fname" target="build-doc-file">
     <fileset dir=".">
      <include name="doc/ChangeLog"/>
      <include name="doc/**.txt"/>
      <include name="doc/**.rst"/>
      <include name="doc/**/*.rst"/>
      <exclude name="doc/LICENSE.txt"/>
      <exclude name="doc/developers/TODO.rst"/>
     </fileset>
   </foreach>
  </target>
 
 
  <target name="build-doc-file" depends="check"
   description="Builds a single documentation file. Pass file path as $fname"
  >
   <echo msg="${fname}"/>
   <php function="preg_replace" returnProperty="outfile">
    <param value="/^(.+)(.rst|.txt)$/"/>
    <param value="dist/\1.html"/>
    <param value="${fname}"/>
   </php>
 
   <!-- only render file if the doc file is newer than the html file -->
   <property name="isuptodate" value="false"/>
   <uptodate property="isuptodate" srcfile="${fname}" targetfile="${outfile}" />
   <if>
    <not><istrue value="${isuptodate}"/></not>
    <then>
     <exec
      command="rst2html --exit-status=2 ${fname} ${outfile}"
      checkreturn="1"
      />
    </then>
   </if>
 
  </target>

Yes, totally ugly and unreadable. Since I am on vacation, I took the time to write a separate rST task that takes all the work from you:

  <target name="build-docs">
   <rST uptodate="true">
     <fileset dir="doc">
      <include name="ChangeLog"/>
      <include name="**.txt"/>
      <include name="**.rst"/>
      <include name="**/*.rst"/>
      <exclude name="LICENSE.txt"/>
      <exclude name="developers/TODO.rst"/>
     </fileset>
   </rST>
  </target>

It automatically renders HTML but supports all other formats supported by Python's docutils, supports file name mappers, multiple filesets, has filter chain support and renders files only if the sources are newer (and you want that). Have a look at the README.

The code is available on github and gitorious, and I'm trying to get it into the official phing distribution . The task is part of phing since version 2.4.7.

@Mario B.: Do that with Ant.