Re: [Docutils-users] writing a directive to insert rst content into a document

[David G. <go...@py...>]

On Thu, Apr 30, 2009 at 10:45, Bernhard Leiner
<mai...@gm...> wrote:
> I'm trying to write a supposedly simple docutils "my_insert" directive
> that is capable of inserting arbitrary rst content into a document.
> Basically this directive should work as follows:
>
> .. my_insert:: keyword
>
> Inside the run() method of the "my_insert" directive, depending on the
> "keyword", a function is called which returns some string in rst
> format.
...

It sounds like the "include" directive would serve your purposes. If
not, I suggest you take a look at the source for he "include"
directive, in docutils/parsers/rst/directives/misc.py. Most of its
"run" method is involved with opening the external file and selecting
the range of lines to include. The last 3 lines are relevant to your
case:

            include_lines = statemachine.string2lines(include_text,
                                                      convert_whitespace=1)
            self.state_machine.insert_input(include_lines, path)
            return []

The 1st line converts the text into lines, as expected by the parser.
The 2nd line inserts these lines into the input, so they'll be parsed
normally. The 3rd line returns an empty list, which means nothing is
inserted into the document tree. The parsing will take care of that.

-- 
David Goodger <http://python.net/~goodger>