自定义Sphinx解析器如何设置文档标题以消除toctree警告

我正在尝试用Sphinx为非Python（SKILL语言）项目生成文档，多数函数带有文档字符串，所以初步方案是编写自定义解析器，从文件中提取procedure相关信息。

当前解析器结构如下：

from docutils import nodes
from sphinx.parsers import Parser

class MySkillParser(Parser):
    supported = ("skill",)  # 声明支持的语言
    def parse(self, inputstring, document):
        # 解析inputstring中的文档并动态生成内容
        txt = nodes.Text('HI')
        document += txt

def setup(app):  # 加载扩展时调用
    app.add_source_suffix('.il', 'skill')
    app.add_source_parser(MySkillParser)

    return {'version': '0.1'}

解析器基本可正常运行，但会触发警告：
WARNING: toctree contains reference to document 'myfile' that doesn't have a title: no link will be generated

当在index等文档的toctree中引用myfile时就会出现该警告。myfile.il能被解析生成HTML文件（内容为"HI"），但Sphinx无法识别文档标题，因此不会生成对应的目录条目。

我需要知道：如何让Sphinx识别自定义解析器处理的文档标题？

我参考过两个类似问题，但它们针对的是现成的rst或md解析器，而非自定义解析器。根据Sphinx文档，文件顶部的字段列表会作为元数据存入环境，但我尝试了多种修改环境的方法均无效，不确定是否该由解析器负责设置标题。

要让Sphinx识别文档标题，你需要在自定义解析器中完成两个关键操作：向文档添加标题节点，并同步设置文档的元数据属性，这样Sphinx就能在toctree中正确识别标题并生成链接。

修改后的解析器代码如下：

from docutils import nodes
from sphinx.parsers import Parser

class MySkillParser(Parser):
    supported = ("skill",)  # 声明支持的语言
    def parse(self, inputstring, document):
        # 1. 从SKILL文件内容中提取标题（示例为固定文本，实际替换为真实提取逻辑）
        title_text = "我的SKILL文档标题"
        
        # 创建标题节点并添加到文档中
        title_node = nodes.title(text=title_text)
        document += title_node
        
        # 2. 设置文档的title元数据，让Sphinx环境能读取到标题
        document['title'] = title_text

        # 添加其他内容节点（原有的文本内容）
        paragraph = nodes.paragraph()
        paragraph += nodes.Text('HI')
        document += paragraph

def setup(app):  # 加载扩展时调用
    app.add_source_suffix('.il', 'skill')
    app.add_source_parser(MySkillParser)

    return {'version': '0.1'}

核心要点： #

• 添加标题节点：必须向文档的body中插入nodes.title类型的节点，这是Sphinx识别文档标题的核心标识。实际使用时，你可以从SKILL文件的文档字符串（比如文件顶部的注释块）中提取真实标题，替换示例中的固定文本。
• 同步元数据：设置document['title']属性是为了让Sphinx的内部环境能正确读取标题信息，彻底消除toctree的警告。
• 若需要从SKILL文件的特定位置提取标题，可在parse方法中先对inputstring做字符串解析。例如，如果SKILL文件顶部有; 文档标题：XXXXX这样的注释，就可以通过正则匹配或字符串切片提取标题内容。

内容的提问来源于stack exchange，提问作者MayeulC