Sphinx文档配置：实现不同页面展示不同粒度的函数文档

需求背景 #

• features_dict页面仅展示feature_eng_actes_liq.py中函数的描述部分（如示例中的Return the sum of a and b）
• feature_eng_actes_liq页面展示完整的函数文档（描述、参数、返回值）

可行解决方案 #

方法一：自定义文档字符串处理函数（推荐） #

这种方法通过监听autodoc-process-docstring事件，根据当前页面动态截断文档内容，适配性更强。

1. 修改Sphinx配置文件conf.py，添加以下代码：

from sphinx.ext.autodoc import FunctionDocumenter
import re

def truncate_docstring(app, what, name, obj, options, lines):
    # 仅针对features_dict页面处理
    if 'features_dict' in app.builder.current_docname:
        # 定位Parameters分隔线的位置，截断后续内容
        for i, line in enumerate(lines):
            if line.strip() == 'Parameters':
                del lines[i:]
                break
        # 清理末尾空行
        while lines and lines[-1].strip() == '':
            del lines[-1]

def setup(app):
    app.connect('autodoc-process-docstring', truncate_docstring)

2. 配置features_dict.rst，正常引用目标函数：

.. automodule:: feature_eng_actes_liq
   :members: my_function
   :undoc-members:
   :show-inheritance:

3. 配置feature_eng_actes_liq.rst，保持完整文档展示：

.. automodule:: feature_eng_actes_liq
   :members: my_function
   :undoc-members:
   :show-inheritance:

方法二：结合autodoc.between的条件适配 #

如果希望继续使用sphinx.ext.autodoc.between，可以通过条件判断仅在目标页面生效：

1. 修改conf.py：

from sphinx.ext.autodoc import between

def setup(app):
    # 为features_dict页面添加截断规则
    def conditional_between(app, what, name, obj, options, lines):
        if 'features_dict' in app.builder.current_docname:
            # 仅保留Parameters之前的内容
            between('^.*$', '^Parameters', exclude=True)(app, what, name, obj, options, lines)
        else:
            # 其他页面恢复完整文档
            lines[:] = obj.__doc__.split('\n')
    
    app.connect('autodoc-process-docstring', conditional_between)

注意：此方法依赖文档字符串的格式严格匹配，若文档中Parameters的缩进或写法不一致，可能导致失效，因此更推荐第一种方法。

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