如何用%(before_notes)s和%(after_notes)s自动填充Scipy风格文档？

1. 复用Scipy的文档模板机制 #

Scipy的rv_continuous子类文档里的%(before_notes)s、%(example)s等占位符，对应scipy.stats._distn_infrastructure.py中的_docstring_replacement_dict字典，里面预定义了通用的说明文本、示例框架等内容。你可以直接在自定义分布的docstring中使用这些占位符，再通过两种方式完成替换：

方式一：利用Scipy内置方法自动处理

Scipy的rv_continuous类提供了_update_docstring方法，会自动用官方的替换字典格式化你的docstring：

from scipy.stats import rv_continuous

class MyCustomDist(rv_continuous):
    """
    自定义连续概率分布

    %(before_notes)s

    Notes
    -----
    该分布的概率密度函数(PDF)定义为：
    $f(x) = ...$  # 此处填写你的自定义公式

    %(after_notes)s

    %(example)s
    """
    def _pdf(self, x, *args):
        # 实现PDF计算逻辑
        return ...

# 自动完成文档字符串格式化
MyCustomDist._update_docstring()

方式二：手动导入替换字典格式化

如果自动方法不生效，可手动导入替换字典完成字符串替换：

from scipy.stats import rv_continuous
from scipy.stats._distn_infrastructure import _docstring_replacement_dict

class MyCustomDist(rv_continuous):
    """
    自定义连续概率分布

    %(before_notes)s

    Notes
    -----
    该分布的概率密度函数(PDF)定义为：
    $f(x) = ...$

    %(after_notes)s

    %(example)s
    """
    def _pdf(self, x, *args):
        return ...

# 手动替换占位符
MyCustomDist.__doc__ = MyCustomDist.__doc__ % _docstring_replacement_dict

2. 配置Sphinx适配Scipy风格文档 #

要让Sphinx正确解析格式化后的文档，需调整项目根目录下的conf.py配置：

1. 启用必要扩展：

extensions = [
    "sphinx.ext.autodoc",       # 自动生成API文档
    "sphinx.ext.napoleon",      # 解析Google/Scipy风格的docstring
    "sphinx.ext.intersphinx"    # 支持Scipy官方文档的交叉引用
]

2. 配置交叉引用与自动文档选项：

# 关联Scipy官方文档，方便用户跳转查看基础概念
intersphinx_mapping = {
    "scipy": ("https://docs.scipy.org/doc/scipy/", None)
}

# 确保autodoc读取格式化后的完整docstring
autodoc_member_order = "bysource"
autodoc_default_options = {
    "members": True,
    "undoc-members": True
}

3. 自定义示例（可选） #

如果官方的%(example)s模板不符合你的需求，直接在docstring中替换该占位符为自定义示例即可，比如：

class MyCustomDist(rv_continuous):
    """
    自定义连续概率分布

    %(before_notes)s

    Notes
    -----
    该分布的概率密度函数(PDF)定义为：
    $f(x) = ...$

    %(after_notes)s

    Examples
    --------
    >>> from my_module import MyCustomDist
    >>> dist = MyCustomDist()
    >>> dist.pdf(0.5)
    0.75
    """
    # ... 类实现 ...

验证方法 #

在代码中打印MyCustomDist.__doc__，确认所有占位符已被正确替换为实际文本，再运行sphinx-build生成文档，检查最终渲染效果。

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