Re: [Docutils-users] nested field lists in custom directives

[Robin S. <rj...@ro...>]

To time travellers from the future (searching the list-archive):

This is actually really simple, when you figure out how it all works. All
you need to do to parse the content of a directive is the following:

node = nodes.Element()
self.state.nested_parse(self.content, self.content_offset, node)

First we create a node of class nodes.Element(). This node is not actually
part of the document tree! It is just a dummy container for us to put our
content while we work with it. Next we call the state.nested_parse method.
This method is inherited by all directives. It takes the content given to
the directive (that is everything after ".. driective::" that is indented
but isn't part of the options field list) and parses it and places the
output into the dummy container we just created (node). Now to access the
content we can access it as if it were a nested list.

So in my case node looked like this:
[Element[bullet_list[list_item[paragraph[Text]]]]].
To access the bullet_list node I just use node[0]. To access an attribute
of the bullet_list node I use node[0]['key']. Calling print(node) will show
you what your particular node looks like.

Maybe all that is really obvious, but it took me several days of fruitless
pain trying to understand states.py and statemachine.py, before I figured
it out.

For a more thorough walk thru of parsing the content of custom directives
see
https://github.com/vorpalvorpal/hovercraft/blob/master/hovercraft/local_directives/example.__init__.py


> optional_arguments could have been defined as "-1 is equivalent to
> infinity" (or some other sentinel value), but it wasn't. In cases like
> this, when you want to have an unlimited number, the standard idiom is
> to use sys.maxint, a very large number that is close enough to
> infinity for our purposes.
>


To time travellers from the future: python3 replaced sys.maxint with
sys.maxsize.

To David:
Thanks for your pointers. It made something that would have been impossible
for me, possible.

Cheers,
Robin.