如何用Sphinx从Python字典提取描述并自动插入.rst文档？

这个需求完全可行，核心思路是自定义Sphinx扩展指令，直接读取Python字典中的指定键值并渲染到文档里，完美解决重复维护的问题，替代只能输出整个字典的autodoc。

实现步骤： #

1. 编写自定义Sphinx扩展
   在你的Sphinx项目根目录新建一个扩展文件（比如dict_extension.py），内容如下：

   from sphinx.util.docutils import SphinxDirective
   from docutils import nodes
   import importlib
   
   class DictItemDirective(SphinxDirective):
       required_arguments = 1  # 格式：模块名.字典名["键名"]
   
       def run(self):
           # 解析传入的参数，比如 "description_mapping.dashboard_descriptions['cpu_monitor']"
           expr = self.arguments[0]
           try:
               # 动态导入模块并获取字典项
               module_name, rest = expr.split('.', 1)
               module = importlib.import_module(module_name)
               value = eval(f"module.{rest}", {"module": module})
               # 将值转为文档节点
               text_node = nodes.Text(value)
               return [text_node]
           except Exception as e:
               # 出错时返回错误提示
               error_node = nodes.error(text=f"无法获取字典项: {str(e)}")
               return [error_node]
   
   def setup(app):
       app.add_directive("dict-item", DictItemDirective)
       return {"version": "0.1", "parallel_read_safe": True}
   

2. 在Sphinx配置中启用扩展
   打开conf.py，在extensions列表中添加自定义扩展：

   extensions = [
       # 其他已有扩展...
       "dict_extension"
   ]
   

   同时确保description_mapping.py所在路径被加入Python搜索路径，可在conf.py中添加：

   import sys, os
   sys.path.insert(0, os.path.abspath('../'))  # 根据实际路径调整
   

3. 在.rst文件中调用指令
   直接在需要插入描述的位置使用自定义指令，传入字典的路径和键：

   CPU监控仪表盘
   ------------
   .. dict-item:: description_mapping.dashboard_descriptions["cpu_monitor"]
   

替代方案（无需写扩展） #

如果不想写自定义扩展，可以用Sphinx的eval-rst结合Python代码块快速实现，但需要额外处理代码块隐藏：

内存监控仪表盘
------------
.. eval-rst::
   .. code-block:: python
      :class: hidden
      from description_mapping import dashboard_descriptions
      print(dashboard_descriptions["memory_monitor"])

（注：需在项目CSS中添加.hidden { display: none; }来隐藏代码块，只显示打印的描述内容）

关键说明 #

• 自定义扩展的方式更灵活，支持复杂的字典结构，渲染结果干净，适合正式文档场景。
• 所有方案都能保证描述内容只在description_mapping.py中维护一次，完全遵循DRY原则。

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