Sphinx docxbuilder和自定义扩展

Question

我在扩展中定义了一个自定义节点(类似于sphinx页面上的TODO示例(。

问题是，这个扩展通过visit_my_node/depart_my_node方法用于html输出，但我希望为docxbuilder实现类似的东西。

我在docxbuilder文档中看到，我可能应该使用翻译器，但由于不太熟悉这个概念，我真的不知道如何使用。

我也在SO上看到了这个话题，建议我也许应该重建构建器，但我想在翻译方面得到一些有价值的意见。

下面，您将找到一个自定义节点的扩展实现的代码示例(有点旧，但您应该了解已经做了什么(

from docutils import nodes
from docutils.parsers.rst import directives
from docutils.parsers.rst import Directive

class myNode(nodes.General, nodes.Element):
def __init__(self, options, *args, **kwargs):
super(myNode, self).__init__(options, *args, **kwargs)
self.__options = options
def get_options(self):
return self.__options


class myDirective(Directive):
"""
Requirement entry.
"""

has_content = True
required_arguments = 0
optional_arguments = 0
final_argument_whitespace = False
option_spec = {
'name': directives.unchanged_required,
'title': directives.unchanged_required,
'parents': directives.unchanged} # boolean}
def run(self):
my_node = myNode(self.options)
self.state.nested_parse(self.content, self.content_offset, my_node )
return [my_node]

def visit_my_node(self, node):

name = node.get_options()['name']

if len(node.get_options()['parent']) > 0:
parent = ", ".join([x.strip() for x in node.get_options()['parent'].split(',')])
else:
parent = "design"

self.body.append('<div class="mynode">n')
self.body.append('t<p class="my-header"><strong>' + name + '; ' + parent + '</strong></p>n')
self.body.append('t<div class="my-content">n')
def depart_my_node(self):
self.body.append('t</div>n')
self.body.append('t<p class="my-footer"><strong>END</strong></p>n')
self.body.append('</div>n')
def setup(app):
app.add_node(myNode,
html=(visit_my_node, depart_my_node))

app.add_directive("mynode", myDirective)

return {'version' : '0.1'}

Answer 1

如果您的输出代码不是太复杂(例如，只有一些div容器、段落、一些文本(，我会尽量避免使用自定义生成器访问者函数。主要是因为你需要为每个构建器维护一个解决方案，而且有很多构建器，你可能会错过一些。

我会尝试将您的自定义指令节点转换为一些标准的docutils节点，这样每个构建器都可以处理它

因此，您可以向sphinx事件doctree-resolved添加一个处理程序，然后在当前doctree中搜索自定义节点。然后，该节点将被标准docutil节点的嵌套列表所取代，例如node.replace_self(docutils.nodes.Text('Some simple text'))。

为指令创建这个嵌套的docutils节点树可能比在访问者函数中添加HTML字符串更复杂。但好处是，你只需要做一次，就可以开箱即用地支持所有狮身人面像建筑商。

免责声明：我是Sphinx Needs的维护者，它在所有指令中都使用上述机制。