Either option will work, although option 2 is expressed wrong.On Wed, Apr 24, 2013 at 4:34 PM, Carl Cerecke <firstname.lastname@example.org> 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
> .. 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
> 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?
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/misc.py) for an example of
If your source data is easily parseable but not already reST,
option 1 may be easier.
David Goodger <http://python.net/~goodger>