如何为Sphinx automodule成员修剪部分前置导入路径？

这个需求确实很合理——既不想让函数签名带着一长串父模块路径显得臃肿，又不想完全丢掉模块上下文导致读者分不清函数归属。下面分享几个实用的解决方案：

方案1：用currentmodule限定上下文（最简单直接） #

你可以通过.. currentmodule::指令提前指定父模块的范围，这样automodule生成的函数签名就只会显示相对这个父模块的路径。

举个例子，原来的写法是：

.. automodule:: super.cool.thing.my_module
   :members:
   :undoc-members:

修改成：

.. currentmodule:: super.cool.thing

.. automodule:: my_module
   :members:
   :undoc-members:

这样生成的函数就会显示为my_module.function_name，既保留了模块级的归属信息，又砍掉了前面冗余的super.cool.thing部分。

方案2：自定义签名处理逻辑（灵活适配特殊需求） #

如果需要更精细的控制（比如只想保留最后N级路径），可以通过Sphinx的事件钩子来修改签名显示。在你的conf.py中添加以下代码：

from sphinx.ext.autodoc import FunctionDocumenter

def trim_long_module_path(app, what, name, obj, options, signature, return_annotation):
    # 只处理函数的签名
    if what == 'function' and signature:
        # 把完整路径按点分割，这里只保留最后两级（模块名+函数名）
        path_parts = name.split('.')
        if len(path_parts) >= 2:
            shortened_name = '.'.join(path_parts[-2:])
            # 替换签名里的完整路径为短路径
            updated_signature = signature.replace(name, shortened_name)
            return (updated_signature, return_annotation)
    # 其他情况保持原样返回
    return (signature, return_annotation)

def setup(app):
    # 注册事件处理函数
    app.connect('autodoc-process-signature', trim_long_module_path)

这段代码会监听autodoc-process-signature事件，自动把函数的完整导入路径截断成最后两级。你可以根据自己的需求调整path_parts[-2:]的切片范围——比如改成path_parts[-1:]就只保留函数名，和add_module_names=False效果一致。

方案3：结合add_module_names和currentmodule的折中方案 #

如果全局设置add_module_names=False后，你还是想保留当前模块的上下文，可以在每个模块的文档中用currentmodule指定模块，这样函数会显示模块名+函数名：

首先在conf.py中设置：

add_module_names = False

然后在文档里：

.. currentmodule:: super.cool.thing.my_module

.. automodule:: super.cool.thing.my_module
   :members:
   :undoc-members:

这样生成的函数签名会是my_module.function_name，既不会有过长的父路径，也不会让函数名孤立无援。

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