如何以编程方式从 Python 字典生成一些文档并使用 Sphinx 将其插入到 .rst 文件中

Question

我正在编写一个配置工具，可以自动部署一些监控仪表板。每个仪表板都有书面说明，可在工具中找到，并且可以在已部署的仪表板中找到。但我们还有一些重复此描述的功能文档，以便最终用户可以在代码之外阅读它。所以基本上我们有以下内容：

1. 描述_映射.py

dashboard_description_mapping = {"dashboard_1": "This dashboard achieves xyz"}

2. 自述文件.rst

Templates
=========

Descriptions
------------

* **dashboard_1**
    
    This dashboard achieves xyz

我简化了方法，在实际情况中，我们有许多仪表板和描述，它们都在文件description_mapping.py和README.rst中重复。

我希望能够执行某种命令，为我提供以下功能：

Templates
=========

Descriptions
------------

* **dashboard_1**
   
   .. magic_command: description_mapping.dashboard_description_mapping.get("dashboard_1")

然后渲染就好像描述被自动抓取一样，基本上我就不再违反 DRY 原则了。

这可能吗？我搜索了一段时间，遇到了这个前一个问题，但这似乎没有达到我的需要：

1. 如何使用Python以编程方式生成部分Sphinx文档？
2. 在Sphinx文档中显示字典数据

我想抓取字符串，而不是基本上打印出整个字典。

我尝试使用..autodoc的现有功能，但这并没有给我想要的输出，而只是打印出字典。

Answer 1

我实际上想出了如何做到这一点，我使用了来自以下位置的自定义 ..exec 指令：https://stackoverflow.com/a/10146415/8580574并且基本上只是打印了我想要的格式：

.. exec::
    from title_desc_mappings import dashboard_description_mapping
    
    for key, value in dashboard_description_mapping.items():
        if key.startswith('dashboard'):
            print(f"* **{key}**\n\n")
  
            if value == '':
                print("  No description available.\n")
            else:
                print(f"  {value}\n")

希望这对其他人有帮助