如何在Sphinx自定义指令中嵌套解析Markdown内容？

问题背景 #

在自定义Sphinx指令中，使用nested_parse默认仅支持解析RST格式内容，尝试直接调用MystParser或通过include指令指定解析器均出现错误，需求是在现有节点中追加解析后的Markdown内容。

可行解决方案 #

方法1：临时切换解析器后使用nested_parse #

利用当前Sphinx环境的Myst解析器，临时替换文档解析器，通过nested_parse解析Markdown内容，完成后恢复原解析器。

from sphinx.util.docutils import SphinxDirective
from myst_parser.sphinx_parser import MystParser
from docutils.statemachine import ViewList
import docutils.nodes

class CustomMarkdownDirective(SphinxDirective):
    def run(self):
        # 创建要追加内容的目标节点
        target_section = docutils.nodes.section()
        # 待解析的Markdown内容
        markdown_text = """
**加粗文本** `代码片段`

带*斜体*的段落
"""
        
        # 获取当前环境的Myst解析器实例
        myst_parser = self.env.get_parser("md")  # 或指定"myst"，取决于配置
        
        # 保存原解析器，临时切换为Myst解析器
        original_parser = self.state.document.parser
        self.state.document.parser = myst_parser
        
        try:
            # 将Markdown文本转为ViewList，调用nested_parse解析到目标节点
            vl = ViewList(markdown_text.splitlines(), source=self.content.source)
            self.state.nested_parse(vl, 0, target_section)
        finally:
            # 恢复原解析器，避免影响后续处理
            self.state.document.parser = original_parser
        
        return [target_section]

方法2：直接解析Markdown为节点后追加 #

通过Myst解析器将Markdown文本解析为docutils节点，直接添加到现有节点中：

from sphinx.util.docutils import SphinxDirective
from myst_parser.sphinx_parser import MystParser
import docutils.nodes

class CustomMarkdownDirective(SphinxDirective):
    def run(self):
        target_section = docutils.nodes.section()
        markdown_text = "**测试Markdown** 内容，包含`代码`和*强调*"
        
        # 创建关联当前环境配置的document
        temp_doc = docutils.utils.new_document(
            self.env.docname,
            self.state.document.settings
        )
        # 获取Myst解析器并解析文本
        myst_parser = self.env.get_parser("md")
        myst_parser.parse(markdown_text, temp_doc)
        
        # 将解析后的节点追加到目标section
        target_section.extend(temp_doc.children)
        
        return [target_section]

之前尝试的错误原因 #

1. 直接新建docutils.document报错：
   单独创建的document缺少Sphinx环境关联的属性（如env），MystParser在Sphinx环境下运行依赖这些属性，需使用当前文档的settings创建临时document。

2. 临时文件include方法报错：
   错误expected str, bytes or os.PathLike object, not method大概率是因为写入临时文件后未调用tmp.flush()，导致内容未同步到磁盘，或是路径引用格式问题；且该方法冗余，直接解析文本更高效。

内容的提问来源于stack exchange，提问作者Ondřej Navrátil