python-sphinx - 如何在节点中为指令添加 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

您可以构建一个 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 的任何(很容易找到的)相关文档。作为指南。