Python函数文档中如何合理引用其他类方法的参数文档？

问题1：引用另一个类或方法的首选方式 #

不同文档规范与工具对应不同的首选方案，核心目标是保证可读性、工具兼容性与可维护性：

• Sphinx兼容的交叉引用风格：使用:class:或:meth:角色标记目标对象，比如:meth:Foo.update``，既支持Sphinx生成可跳转的文档，PyCharm、VS Code等主流IDE也能识别该标记，在重构类/方法名称时自动同步更新引用。
• Google/NumPy风格：直接写出目标对象的全限定名称，比如参考 Foo.update 方法的参数定义，简洁直观，无需额外工具依赖，多数IDE也能识别名称并支持跳转与重构同步。
• PEP 257轻量风格：用自然语言明确指向目标，比如参数规则同Foo类的update方法，适合快速文档场景，可读性强，无学习成本。

问题2：Bar.set_cfg引用Foo.update参数文档的具体方案 #

针对你提供的代码，推荐以下几种可辩护的方案，按优先级排序：

方案1：Sphinx交叉引用标记（IDE重构友好） #

修改Bar.set_cfg的文档字符串，使用Sphinx的:meth:角色标记，兼顾文档生成与IDE重构支持：

class Bar:
    cfg = Foo()
    
    def set_cfg(self, **kwargs):
        """Set the cfg. 
        
        Keyword Args:
            所有参数定义详见 :meth:`Foo.update` 的关键字参数说明
        """
        self.cfg.update(**kwargs)

主流IDE会识别:meth:标记，在重构Foo.update名称时自动更新引用，同时Sphinx生成文档时会将其转为可点击的链接。

方案2：IDE识别的全限定名称（无工具依赖） #

如果不依赖文档生成工具，直接用反引号包裹全限定名称，IDE会将其识别为可跳转的符号，且支持重构同步：

class Bar:
    cfg = Foo()
    
    def set_cfg(self, **kwargs):
        """Set the cfg. 
        
        Keyword Args:
            参考 `Foo.update` 的关键字参数定义
        """
        self.cfg.update(**kwargs)

这种方式无需额外配置，可读性强，同时满足IDE的跳转与重构需求。

方案3：动态文档注入（自动化同步） #

如果需要完全避免复制粘贴，可借助第三方库（如docstring-parser）提取目标方法的文档并合并，实现内容自动同步：

from docstring_parser import parse

def inherit_doc_from(source_method):
    def decorator(target_func):
        # 解析源方法与目标方法的文档
        source_doc = parse(source_method.__doc__)
        target_doc = parse(target_func.__doc__)
        # 合并关键字参数部分
        target_doc.meta.extend(source_doc.meta)
        # 重新生成文档字符串
        target_func.__doc__ = target_doc.render()
        return target_func
    return decorator

class Bar:
    cfg = Foo()
    
    @inherit_doc_from(Foo.update)
    def set_cfg(self, **kwargs):
        """Set the cfg."""
        self.cfg.update(**kwargs)

该方案能实现文档内容的自动同步，但需要依赖第三方库，且IDE实时预览可能无法直接显示合并后的完整文档，适合对文档自动化要求高的场景。

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