如何使用 %(before_notes)s 和 %(after_notes)s 自动填充文档

Question

我为一个研究项目编写了一个模块，该模块实现了一些概率分布作为 Scipy 的

rv_continuous

类的子类。现在我想为我的模块创建一些文档，并且我希望该文档与 Scipy 的一致。我看到 Scipy 的概率分布文档字符串（例如

scipy.stats.uniform

here 的文档字符串）使用字典插入样板文本并（我认为）自动生成示例：

%(before_notes)s

、

%(example)s

和

%(after_notes)s

.

据我所知，这本词典保存在

scipy.stats._distn_infrastructure.py

中，但我不知道如何使用它。我该怎么办？当然，我正在使用 Sphinx。

Answer 1

这样做的逻辑是这里。

本质上，其工作方式是，每当实例化此类的实例时，它都会使用

self.__doc__

访问自己的文档字符串，操作该字符串，然后通过分配回

self.__doc__

来更改其文档字符串。 scipy._lib.doccer.docformat函数负责执行字符串操作。

要创建文档，每当导入

scipy.stats

时，都会实例化这些类之一并将其分配给

scipy.stats.uniform

。从技术上讲，您看到的文档是实例的文档，而不是类的文档，您可以在此处的文档页面上注意到：

由于

uniform

包含在模块的

__all__

中，但

uniform_gen

不包含，Sphinx 会为此实例生成文档页面，而不是类。

据我所知，如果你继承

rv_continuous

，你将默认获得此功能。