Question

我正在Sphinx中编写自定义角色/指令，我需要插入一个节点，我将文本字符串解释为reStructuredText。有没有办法做到这一点？

我找到了这个来源http://agateau.com/2015/docutils-snippets，其中说明了如何使用docutils.nodes类以编程方式构建doctree片段，例如

class BulletList(Directive):
    def run(self):
        fruits = ['Apples', 'Oranges', 'Bananas']

        lst = nodes.bullet_list()
        for fruit in fruits:
            item = nodes.list_item()
            lst += item
            item += nodes.paragraph(text=fruit)

        return [lst]

我想做的是像

:myrole:`this is *really* cool|trade|`

在conf.py中执行此操作：

def myrole(name, rawtext, text, lineno, inliner, options={}, content=[]):
    # somehow convert the "text" parameter into docutils nodes
    # by interpreting it as RST
    nodes = ???? what goes here ???
    return nodes, []

def setup(app):
    app.add_role('myrole', myrole)

Answer 1

您要在指令的run()方法中使用self.state.nested_parse：

许多指令将包含更多必须解析的标记。为此，请使用Directive.run（）方法中的以下API之一：

self.state.nested_parse

sphinx.util.nodes.nested_parse_with_titles() –这允许解析内容中的标题。

两个API都将内容解析到给定的节点中。它们的用法如下：
node = docutils.nodes.paragraph()
# either
nested_parse_with_titles(self.state, self.result, node)
# or
self.state.nested_parse(self.result, 0, node)

This question about creating input using a ViewList()也可能是相关的。

我不确定您是否可以在角色中使用它。显然，由于角色在任何情况下都是函数，因此您将无法使用self.变体。

如何以编程方式将reStructuredText解释为docutil节点？

1 个答案: