sphinx 文档：如何在 sphinx 事件处理程序中呈现动态的第一个内容？

Question

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

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

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

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

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

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

但那是错误的地方，因为我的扩展还没有收集所有对象。

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

在此函数中，我可以添加任何类型的 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 函数，但这需要一个 'state' 对象，它只能在指令中使用，而不能在事件处理程序中使用。

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

Answer 1

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

来自 sphinx-needs 的简化代码片段：

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)

sphinx 文档：如何在 sphinx 事件处理程序中呈现动态的第一个内容？

sphinx doc: How to render dynamic rst content inside sphinx event handlers?

python

events

python-sphinx

directive

plantuml