Spyder编辑器中如何让自定义函数的docstring跨脚本正常显示

问题核心原因 #

Spyder 5.0.5 依赖 Jedi 引擎做静态代码分析和文档索引，默认只会索引同脚本、已安装第三方包以及加入Python路径的目录下的代码文件，跨脚本导入时如果自定义函数所在目录未被索引，就会出现无文档提示的问题。

解决方法 #

方法1：临时添加路径到Spyder Python路径（适合临时开发场景） #

• 复制自定义函数所在脚本的父文件夹完整路径
• 打开Spyder顶部菜单栏 工具 -> PYTHONPATH管理器
• 点击添加路径，粘贴刚才复制的路径，勾选路径前的复选框，点击同步到Spyder后关闭窗口
• 重启IPython内核（点击控制台右上角的重启图标，或直接重启Spyder）即可生效

方法2：将自定义代码封装为可安装包（适合长期复用场景） #

• 在自定义脚本所在目录新建空的__init__.py文件，标识该目录为Python可识别的包
• 同目录新建setup.py文件，写入基础包配置，示例如下：

from setuptools import setup, find_packages

setup(
    name="custom_utils",
    version="0.1",
    packages=find_packages(),
)

• 打开Spyder内置终端，cd到该目录下执行 pip install -e . 命令，以开发模式安装自定义包
• 后续任意脚本导入该包下的函数时，都可正常显示docstring

异常排查 #

如果配置完成后还是无法显示，先在调用脚本中执行print(你的函数名.__doc__)：

• 如果能正常打印docstring内容，属于索引缓存问题，点击顶部菜单栏 项目 -> 清理工作区 后重启内核即可
• 如果无法打印，检查导入语句是否正确，自定义函数的docstring是否符合规范（是否用三引号包裹、是否写在函数定义行的下一行）

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