什么是Sphinx autosummary指令中的"生成"选项？

Question

我正在使用sphinx api-doc和autosummary扩展来记录库的API,我真的无法理解generated/下面选项的用途:

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

   module.function_1
   module.function_2
   ...

我已经看到这是sphinx文档,并且在像pandas这样的库中.我正在使用toctree,我的API是自动生成的,但我不明白生成的是什么.我没有看到名为generated的文件夹,也不知道这是什么优点/目的.

谢谢

Answer 1

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

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