Builder and custom extension

[Paul-Antoine Ruby]

Hi all,

I would love to be able to make custom directive work with Docxbuilder, but I'm pretty much lost with the topic.

I logged my answer of this SO topic but was unable to get any valuable answer.

Is this task even possible to do?

[Daniel Woste]

Hi,
answered this also on SO:

If your output code is not too complex (for instance just some div-container, paragraphs, some text) I would try to avoid the custom builder visitor functions. Mainly as you need to maintain one solution for each builder, and as there are many builders, you may miss some.

I would try to transform your custom directive node to some standard docutils nodes, so that each builder can handle it.

So you can add a handler to the sphinx event "doctree-resolved", then you search for your custom node in the current doctree. This node get then replaced by a nested list of standard docutil nodes, e.g. node.replace_self(docutils.nodes.Text('Some simple text')).

The creation of this nested docutils-node-tree for your directive may be more complex than just adding a HTML-string in a visitor function. But the benefit is, you have to do it only once and support 100% of all Sphinx builders out of the box.

Disclaimer: I'm a maintainer of Sphinx-Needs, which is using the above mechanism for all its directives.