8. Cooperation with third party extensions

Docxbuilder supports third party extensions which generate well-formed docutils document tree

However, there are some extensions to generate the tree with their original docutils nodes. Because Docxbuilder does not support the nodes, the all nodes are ignored when building the document. If you want to include the extension contents into the document, you must define the function to handle the node in conf.py.

The following example shows how to define the function to handle third party original node.

Listing 8.1 Example to define a method for third party extension

# Define setup function in conf.py
def setup(app):
    # Define visit method for plantuml node generated by sphinxcontrib.plantuml
    # https://pypi.org/project/sphinxcontrib-plantuml/
    def docx_visit_plantuml(self, node):
        def get_filepath(self, node):
            from sphinxcontrib import plantuml
            _, filepath = plantuml.render_plantuml(self, node, 'png')
            return filepath
        alt = node.get('alt', (node['uml'], None))
        # Docxbuilder provides useful methods. See Docxbuilder API reference.
        self.visit_image_node(node, alt, get_filepath)
    # Add the visit method to Docxbuilder
    import docxbuilder
    translator = docxbuilder.DocxBuilder.default_translator_class
    setattr(translator, 'visit_plantuml', docx_visit_plantuml)