5 ------------------------------------
6 An HTML Chunker for reStructuredText
7 ------------------------------------
10 :Author: Andras Mohari <mayday at vizslamail dot hu>
12 :Status: *Experimental*
13 :Copyright: This document has been placed in the public domain.
15 :Abstract: ``rst2chunkedhtml`` reads standalone reStructuredText source files
16 and produces chunked HTML output. It chunks sections up to a specified
17 depth, and uses the DocUtils HTML writer to convert the chunks to HTML.
26 * Python 2.4 or newer.
27 * A recent development version of DocUtils.
28 * `This patch`_. It adds chunking
29 support to the HTML writer (``docutils/writers/html4css1/__init__.py``).
32 .. _patch: html4css1-external-refs.patch
38 To try rst2chunkedhtml, grab the latest development version of DocUtils, copy
39 the ``docutils`` Python package to a directory of your choice, and apply the
40 patch_ to it. Finally adjust your PYTHONPATH environment variable so that the
41 package can be imported.
47 Let's chunk a file called ``demo.txt``::
50 rst2chunkedhtml --chunk-depth=0 demo.txt demo/index.html
52 This chunks all sections, writes the root chunk to ``demo/index.html``, and
53 all other chunks to ``demo/<id>.html``, where ``<id>`` is the section ID. As
54 you can see above, the directory must already exist, it will not be created
55 for you. Note that if a chunked section node has an ID called ``index``, the
56 filename of the chunk would conflict with that of the root chunk, and
57 rst2chunkedhtml will exit with an error.
63 You can invoke ``rst2chunkedhtml`` the same way you would invoke ``rst2html``::
65 rst2chunkedhtml [options] [<source> [<destination>]]
69 .. vim: set tw=78 ts=3 sw=3 sts=3 et ft=rst: