使用Sphinx autodoc时ReadTheDocs上装饰器函数签名异常求助

嘿，这个问题我碰到过好多次了！本地明明用decorator库的@decorator装饰器把Autodoc显示装饰器签名的问题解决了，结果一部署到ReadTheDocs（RTD）就又翻车，对吧？别着急，这大概率是RTD构建环境里没装decorator依赖导致的！

先看你写的这段备用代码：

try: from decorator import decorator except ImportError: def decorator(f): return f

当RTD的环境里找不到decorator包时，你的自定义装饰器就会用上那个空实现的降级版decorator函数——这个版本根本没法帮你保留原函数的签名信息，所以Autodoc自然又开始显示装饰器的签名了。

下面给你一步步的排查和修复方案：

排查与修复步骤 #

• 第一步：把decorator加到项目依赖里
  你需要把decorator库添加到项目的依赖管理文件中，比如requirements.txt、pyproject.toml（如果用Poetry或Pipenv的话）。RTD在构建文档时会自动安装这些依赖，这样你的备用代码就能加载真正的decorator库，而不是降级版本。
  举个requirements.txt的例子，加一行：

  decorator>=4.0.0
  

• 第二步：检查RTD的构建配置
  登录RTD的项目后台，进入「Advanced Settings」确认两个关键点：

  • 是不是指定了和你本地一致的Python 3版本（比如3.8及以上）
  • 是不是开启了「Install your project inside a virtualenv using setup.py/install」选项，确保项目依赖被正确安装到构建环境中

• 第三步：本地模拟RTD环境验证
  你可以本地创建一个干净的虚拟环境，故意不装decorator库，然后尝试构建文档——如果这时候复现了和RTD上一样的问题，那就能实锤是依赖缺失的原因了。装完decorator再构建，问题应该就消失了。

至于要不要在RTD的GitHub仓库提Issue？先别急着提，先把上面的步骤走完，90%的概率都是依赖配置的问题。如果确认依赖已经正确安装但问题依然存在，再去提Issue也不迟，记得附上你的项目配置文件、依赖清单和RTD的构建日志，方便维护者排查。

等你把依赖问题解决后，那个异常的签名显示应该就能恢复成原函数的正确签名了。

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