如何在Sphinx文档中为模块级函数自动追加'Returns: None'说明

如果你的项目使用Sphinx生成文档，优先选择第一种无侵入的配置方案，不需要修改业务代码即可批量生效：

方案1：自定义Sphinx事件回调（适配Napoleon扩展） #

napoleon_custom_sections仅支持自定义固定格式的通用section，无法实现按需自动插入逻辑，你可以配合Sphinx的autodoc-process-docstring事件钩子实现需求：

• 在Sphinx项目的conf.py文件中添加如下代码：

def add_missing_return_none(app, what, name, obj, options, lines):
    # 仅处理函数/方法类对象
    if what not in ("function", "method"):
        return
    # 已有返回值说明的函数不重复补充
    has_return_section = any("Returns:" in line or "Return:" in line for line in lines)
    if has_return_section:
        return
    # 插入返回None的说明
    lines.append("")
    lines.append("Returns:")
    lines.append("    None")

def setup(app):
    app.connect("autodoc-process-docstring", add_missing_return_none)

• 如果需要自定义规则，比如给特定模块的函数补充其他默认返回值、排除部分特殊函数，只要在上述函数中添加对应的判断逻辑即可。
• 该方案完全不侵入业务代码，配置完成后所有符合条件的函数生成文档时都会自动补全返回值说明，和你手写的原有文档字符串内容完全兼容。

方案2：装饰器动态修改文档字符串（不依赖Sphinx） #

如果你需要运行时查看文档（比如用help()命令）也能看到补全的返回值说明，可以用装饰器实现：

• 先定义通用装饰器：

import functools

def auto_return_none(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    # 仅当原有文档字符串未写返回值说明时补充
    if func.__doc__ and "Returns:" not in func.__doc__ and "Return:" not in func.__doc__:
        func.__doc__ += "\n\nReturns:\n    None"
    return wrapper

• 给需要的模块函数添加装饰器即可：

@auto_return_none
def module_level_function(param1, param2=None, *args, **kwargs):
    """This is an example of a module level function.
    Args:
        param1 (int): The first parameter.
        param2 (Optional[str]): The second parameter. Defaults to None.
    """

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