Question

如何在节点中使用rst？例如，我想输出包含的文件about.rst

class Foo(Directive):

    def run(self):
        return [
            nodes.Text("**adad**"),  # <-- Must be a bold text
            nodes.Text(".. include:: about.rst"),  # <-- Must include file
        ]

Answer 1

您可以构建原始rst数据的ViewList（每个条目一行），让Sphinx解析该内容，然后返回Sphinx为您提供的节点。以下对我有用：

from docutils import nodes
from docutils.statemachine import ViewList
from sphinx.util.compat import Directive
from sphinx.util.nodes import nested_parse_with_titles

class Foo(Directive):
    def run(self):
        rst = ViewList()

        # Add the content one line at a time.
        # Second argument is the filename to report in any warnings
        # or errors, third argument is the line number.            
        rst.append("**adad**", "fakefile.rst", 10)
        rst.append("", "fakefile.rst", 11)
        rst.append(".. include:: about.rst", "fakefile.rst", 12)

        # Create a node.
        node = nodes.section()
        node.document = self.state.document

        # Parse the rst.
        nested_parse_with_titles(self.state, rst, node)

        # And return the result.
        return node.children

def setup(app):
    app.add_directive('foo', Foo)

我必须为项目做类似的事情 - 代替我使用source of the inbuilt autodoc extension作为指南的任何（容易找到的）相关文档。

Answer 2

使用使用第一种语法格式化的内容添加文本节点无济于事。您需要创建第一个节点对象以构建所需的第一个元素树。此外，由于您尝试在示例中包含另一个第一个文件，因此您需要使用嵌套解析，因为事先不知道实际内容且无法进行硬编码。

在第一个指令类的run()方法中，可以调用self.state.nested_parse()方法。它的最初目的是解析指令的内容，如下所示：

# parse text content of this directive
# into anonymous node element (can't be used directly in the tree)
node = nodes.Element()
self.state.nested_parse(self.content, self.content_offset, node)

在您的情况下，您可以尝试打开abour.rst文件，解析并添加将节点树解析为结果节点列表，或者您可以尝试运行嵌套用include伪指令解析字符串常量。

如何在节点中添加第一种格式的指令？

2 个答案: