Sphinx 自动摘要指令中的“生成”选项是什么？

Question

我正在使用 sphinx-apidoc 和 autosummary 扩展来记录库的 API，但我真的无法理解下面 generated/ 选项的用途：

.. autosummary::
   :nosignatures:
   :toctree: generated/

   module.function_1
   module.function_2
   ...

我已经看到这是 Sphinx 文档，在 pandas 等库中。我正在使用toctree，我的 API 正在自动生成，但我不明白生成的是什么。我没有看到一个名为 generate 的文件夹，也不知道这样做的好处/目的是什么。

谢谢

Answer 1

“生成”选项是 Sphinx 放置自动生成的“存根”.rst 文件的输出目录的名称。它不必被称为“生成的”；您可以使用任何名称。

当autosummary_generate 配置变量设置为True 时，Sphinx 会为autosummary 指令中列出的每个条目生成一个 .rst 文件。例如，如果您正在为包含多个类的模块编写文档，则可以使用此功能将每个类的完整文档放在单独的页面上。自动摘要表将包含这些页面的链接。