Thanks, David. That's exactly what I'm looking for.
I'm somewhat embarrassed that I didn't think of the "include" directive as an example of the sort of thing I want to do....


On 25 April 2013 10:57, David Goodger <> wrote:
On Wed, Apr 24, 2013 at 4:34 PM, Carl Cerecke <> wrote:
> I want to create a directive that will insert some dynamically
> generated reST into a document. The actual use case is to
> insert a passage from the bible by reference. (Most of the
> time, a bible-reference becomes a hyperlink, and that is
> achieved with a custom role, but sometimes, I'd like to insert
> the entire passage into the document). I want to be able to
> write:
> .. bible-passage:: John 1:1-4
> and have the actual text of John 1:1-4 appear in the document.
> This needs to be dynamic, as the documents are bible-version
> independent-- the bible version is specified as one of the
> build parameters. There will possibly be some formatting
> involved as well - some verses are poetry and are laid out as
> such. Some verses have translational footnotes which need to
> appear. Some use of italics, and small-caps.
> As far as I can see, there are two options:
> 1. Have the new directive generate nodes directly in the node
> tree.
> 2. Have the new directive generate reST that it recursively
> parses and then inserts the resulting nodes into the node tree.
> Which option is the best? And are there other options that I've
> missed that would be better?

Either option will work, although option 2 is expressed wrong.
Instead, the directive would insert the generated reST into the
document and then let Docutils parse it. The directive wouldn't
do any parsing or node-insertion. See the "include" directive
code (docutils/parsers/rst/directives/ for an example of

If your source data is easily parseable but not already reST,
option 1 may be easier.

David Goodger <>