如何在Sublime Text 4中显示Python库的Docstring？含自定义实现咨询

方法1：配置Pyright启用Docstring显示 #

Pyright默认优先使用类型存根（stubs）而非实际库代码，部分存根缺少完整Docstring。通过修改配置可强制其从库代码提取Docstring：

1. 打开Sublime的LSP设置：Preferences > Package Settings > LSP > Settings
2. 在用户设置区域添加Pyright的自定义配置：

{
  "clients": {
    "pyright": {
      "settings": {
        // 指定Python解释器路径（确保指向你的虚拟环境/系统Python）
        "python.pythonPath": "/usr/bin/python3",
        // 启用从库代码中提取类型和Docstring
        "python.analysis.useLibraryCodeForTypes": true,
        // 强制包含Docstring解析
        "python.analysis.includeDocstrings": true,
        // 自动搜索库路径，若第三方库未被识别可手动添加到extraPaths
        "python.analysis.autoSearchPaths": true,
        "python.analysis.extraPaths": ["/path/to/your/virtualenv/lib/pythonX.X/site-packages"]
      }
    }
  }
}

3. 保存设置后重启Sublime，Pyright会重新索引库文件，之后hover或补全时应能显示Docstring。

方法2：安装完整类型存根包 #

部分第三方库的官方类型存根包含更完善的Docstring，可通过pip安装对应types-*包：

# 示例：安装requests、pandas的类型存根
pip install types-requests types-pandas

Pyright会优先使用这些存根文件，从而显示完整的Docstring。

一、开发自定义Sublime插件补充Docstring #

核心思路是监听Sublime的hover/completion事件，主动调用Python的inspect模块获取对象Docstring，再注入到显示中：

1. 基础插件模板：
   打开Tools > Developer > New Plugin，生成如下基础框架：

import sublime
import sublime_plugin
import inspect
import sys
import os

class DocstringEnhancer(sublime_plugin.EventListener):
    def on_hover(self, view, point, hover_zone):
        if hover_zone != sublime.HOVER_TEXT:
            return
        
        # 获取当前光标处的代码上下文（简化示例，实际需更精准的解析）
        line_region = view.line(point)
        line_content = view.substr(line_region).strip()
        target_obj = None
        
        # 尝试提取要查询的对象名（示例仅处理简单模块/函数名）
        if "." in line_content:
            parts = line_content.split(".")
            target_obj = parts[-1] if len(parts) > 0 else None
        else:
            target_obj = view.substr(view.word(point))
        
        if not target_obj:
            return
        
        # 切换到项目的Python环境（需根据实际情况配置虚拟环境路径）
        env_python_path = view.settings().get("python_interpreter_path", sys.executable)
        sys.path.insert(0, os.path.dirname(env_python_path))
        
        try:
            # 动态导入并获取Docstring
            module = __import__(target_obj)
            docstring = inspect.getdoc(module)
            if docstring:
                view.show_popup(docstring, sublime.HIDE_ON_MOUSE_MOVE_AWAY, point, 600, 400)
        except Exception:
            # 处理导入失败的情况（如对象不是顶层模块）
            pass

2. 关键注意事项：

   • 需要实现更精准的代码上下文解析，识别类、方法、函数的完整路径
   • 需适配项目的虚拟环境，确保能正确导入目标库
   • 可结合LSP的API，监听LSP返回的补全/hover数据，补充缺失的Docstring

3. 测试与发布：

   • 将插件保存到Packages/User目录下（后缀为.py）
   • 发布到Package Control需遵循官方规范，编写包描述文件并提交到Package Control仓库

二、扩展Pyright本身 #

Pyright是TypeScript开发的开源语言服务器，可直接修改其代码实现Docstring增强：

1. 环境准备：

   • 克隆Pyright仓库：git clone https://github.com/microsoft/pyright.git
   • 安装依赖：npm install

2. 核心修改点：

   • 找到Pyright中解析Docstring的模块（如src/analyzer/docstringParser.ts）
   • 修改逻辑，强制优先从库源代码中提取Docstring，而非仅依赖类型存根
   • 优化Docstring的格式化逻辑，确保显示完整的注释内容

3. 编译与测试：

   • 编译Pyright：npm run build
   • 将编译后的packages/pyright/dist目录替换Sublime中LSP-pyright插件的对应路径
   • 测试生效后，可向Pyright官方提交PR贡献功能

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