sphinx doc：如何在 sphinx 事件处理程序中呈现动态 rst 内容？答案

【问题标题】：sphinx doc: How to render dynamic rst content inside sphinx event handlers?sphinx doc：如何在 sphinx 事件处理程序中呈现动态 rst 内容？
【发布时间】：2017-03-29 09:55:06
【问题描述】：

我是sphinx-needs 的维护者，它允许定义需求、错误……

这些对象被存储在相关的指令运行函数中，我最终在我的 sphinx 文档中获得了所有对象的列表。

对象可以相互链接，我想创建这些链接的图表（使用 plantuml 和相关的 sphinx-plantuml 扩展）。

问题是，我不知道如何让 sphinx 添加和重新呈现动态创建的植物图规范。

在指令中，我可以使用 state_machine 来完成：

diagram = generate_plantuml_spec(objects)
self.state_machine.insert_input(
        diagram.split('\n'),
        self.state_machine.document.attributes['source'])

但那是错误的地方，因为我的扩展程序尚未收集所有对象。

所以正确的位置应该在函数内部，当 sphinx 触发事件“doctree-resolved”时执行该函数。

在这个函数中，我可以添加任何类型的 docutils 节点。我的想法是使用生成的图表规范创建一个 node.Text()

 def process_needfilters(app, doctree, fromdocname):
     diagram_data = """"
                    .. plantuml::

                       @startuml
                       node Test
                       @enduml
                    """
     for node in doctree.traverse(needs_diagram):
         content = []
         diagram = nodes.Text(diagram_data, diagram_data)
         content.append(diagram)
         node.replace_self(content)

但是这不会强制 sphinx 呈现内容。

我还发现了一个名为 nested_parse_with_titles() 的 sphinx 函数，但这需要一个“状态”对象，该对象只能在指令中使用，而不能在事件处理程序中使用。

那么，知道如何在 sphinx 事件处理程序中呈现第一个内容吗？

【问题讨论】：

标签： python events python-sphinx directive plantuml

【解决方案1】：

解决方案是直接使用plantuml-extension中的plantuml节点：

来自sphinx-needs的简化代码sn-p：

from sphinxcontrib.plantuml import plantuml

for node in doctree.traverse(MyDirective):
    plantuml_block_text = ".. plantuml::\n" \
                          "\n" \
                          "   @startuml" \
                          "   @enduml"
    puml_node = plantuml(plantuml_block_text, **dict())
    node.replace_self(puml_node)

【讨论】：

这很有趣。这是否允许将 .puml 文件导入 .rst？例如.. uml:: mydir/myfile.puml 之类的东西（我想这不是这样做的方法，但我希望你能理解我的想法）。想法是使用单独的插件管理 .puml 图（例如 PyCharm PlantUML 集成，因为它的性能优于 sphinxcontrib-plantuml 0.8.2）。
我认为您所描述的内容已经可以通过 spinxcontrib-plantuml 实现。即使您的语法示例也是正确的。你的用例也和我为我的狮身人面像项目做的完全一样。 Here 是我们 sphinx 工作流程的简短介绍，其中包含 plantuml + sphinx-needs 集成。