# C.82 rSTTask Renders rST (reStructuredText) files into different output formats. This task requires the `python docutils` installed. They contain `rst2html`, `rst2latex`, `rst2man`, `rst2odt`, `rst2s5`, `rst2xml`. Homepage: <https://gitorious.org/phing/rsttask> Table C.112:聽Attributes NameTypeDescriptionDefaultRequired`file``String`rST input file to rendern/aYes (or fileset)`format``String`Output format: - html - latex - man - odt - s5 - xml htmlNo`destination``String`Path to store the rendered file to. Used as directory if it ends with a `/`.magically determined from input fileNo`uptodate``Boolean`Only render if the input file is newer than the target file`false`No`toolpath``String`Path to the rst2\* tooldetermined from `format`No`toolparam``String`Additional commandline parameters to the rst2\* tooln/aNo`mode``Integer`The mode to create directories with.From umaskNo C.82.1 Features - renders single files - render nested filesets - mappers to generate output file names based on the rst ones - multiple output formats - filter chains to e.g. replace variables after rendering - custom parameters to the rst2\* tool - configurable rst tool path - uptodate check - automatically overwrites old files - automatically creates target directories C.82.2 Examples Render a single rST file to HTML By default, HTML is generated. If no target file is specified, the input file name is taken, and its extension replaced with the correct one for the output format. ``` <?xml version="1.0" encoding="utf-8"?> <project name="example" basedir="." default="single"> <target name="single" description="render a single rST file to HTML"> <rST file="path/to/file.rst" /> </target> </project> ``` Render a single rST file to any supported format The `format` attribute determines the output format: ``` <?xml version="1.0" encoding="utf-8"?> <project name="example" basedir="." default="single"> <target name="single" description="render a single rST file to S5 HTML"> <rST file="path/to/file.rst" format="s5" /> </target> </project> ``` Specifying the output file name ``` <?xml version="1.0" encoding="utf-8"?> <project name="example" basedir="." default="single"> <target name="single" description="render a single rST file"> <rST file="path/to/file.rst" destination="path/to/output/file.html" /> </target> </project> ``` Rendering multiple files A nested `fileset` tag may be used to specify multiple files. ``` <?xml version="1.0" encoding="utf-8"?> <project name="example" basedir="." default="multiple"> <target name="multiple" description="renders several rST files"> <rST> <fileset dir="."> <include name="README.rst" /> <include name="docs/*.rst" /> </fileset> </rST> </target> </project> ``` Rendering multiple files to another directory A nested `mapper` may be used to determine the output file names. ``` <?xml version="1.0" encoding="utf-8"?> <project name="example" basedir="." default="multiple"> <target name="multiple" description="renders several rST files"> <rST> <fileset dir="."> <include name="README.rst" /> <include name="docs/*.rst" /> </fileset> <mapper type="glob" from="*.rst" to="path/to/my/*.xhtml"/> </rST> </target> </project> ``` Modifying files after rendering You may have variables in your rST code that can be replaced after rendering, i.e. the version of your software. ``` <?xml version="1.0" encoding="utf-8"?> <project name="example" basedir="." default="filterchain"> <target name="filterchain" description="renders several rST files"> <rST> <fileset dir="."> <include name="README.rst" /> <include name="docs/*.rst" /> </fileset> <filterchain> <replacetokens begintoken="##" endtoken="##"> <token key="VERSION" value="1.23.0" /> </replacetokens> </filterchain> </rST> </target> </project> ``` Rendering changed files only The `uptodate` attribute determines if only those files should be rendered that are newer than their output file. ``` <?xml version="1.0" encoding="utf-8"?> <project name="example" basedir="." default="multiple"> <target name="multiple" description="renders several rST files"> <rST uptodate="true"> <fileset dir="."> <include name="docs/*.rst" /> </fileset> </rST> </target> </project> ``` Specify a custom CSS file You may pass any additional parameters to the rst conversion tools with the `toolparam` attribute. ``` <?xml version="1.0" encoding="utf-8"?> <project name="example" basedir="." default="single"> <target name="single" description="render a single rST file to S5 HTML"> <rST file="path/to/file.rst" toolparam="--stylesheet-path=custom.css" /> </target> </project> ``` C.82.3 Supported Nested Tags - `fileset` - `mapper` - `filterchain`