如何为Python TOML字段添加可被Sphinx渲染的文档字符串？求类似autoyaml工具

一、为TOML字段添加可被Sphinx渲染的文档字符串 #

TOML本身支持用#添加注释，你可以把这些注释当作字段的文档字符串，再通过Sphinx扩展或自定义脚本将其渲染到文档中：

• 注释规范：在TOML字段上方或同行添加清晰的注释作为字段说明，示例：

  # 全局配置块，包含系统核心运行参数
  [global]
  # 服务监听端口，合法范围1024-65535
  port = 8000
  # 是否启用调试模式，生产环境建议设置为false
  debug = false
  

• Sphinx渲染方案：
  1. 使用专门的Sphinx扩展（如sphinxcontrib-toml），这类扩展会自动解析TOML文件中的注释和字段结构，生成符合Sphinx格式的结构化文档。
  2. 自定义Sphinx指令：如果现有扩展无法满足需求，可编写简单的Python脚本，利用tomllib读取TOML文件，提取注释和字段信息，再通过Sphinx的API生成文档节点。

二、类似sphinxcontrib-autoyaml的TOML工具 #

以下是几个适配Sphinx的TOML文档处理工具，功能与sphinxcontrib-autoyaml类似：

• sphinxcontrib-toml：支持从TOML文件提取层级结构、字段注释及默认值，自动生成Sphinx文档，配置简单，能完整保留TOML的原生结构。
• toml-doc：专注于TOML文件的文档生成，可直接输出Markdown格式内容，也能集成到Sphinx项目中，支持提取字段类型、注释等核心信息。
• 自定义脚本：结合tomllib和Sphinx的autodoc机制，自行实现TOML文档的解析与渲染，灵活性更高，适合有特殊格式需求的场景。

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