如何在节点中为指令添加 rst 格式？

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 文件，因此您需要使用嵌套解析，因为实际内容事先未知且无法硬编码。

在第一个指令class的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 指令解析字符串常量。

Answer 2

您可以构建 ViewList 原始数据（每个条目一行），让 Sphinx 解析该内容，然后 return 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 作为指南。

如何在节点中为指令添加 rst 格式？

How to add rst format in nodes for directive?

restructuredtext

docutils

python-sphinx