多数人卡在Ctrl+Shift+2没反应，根本原因是光标未置于def/class行首，且Sublime默认未绑定该快捷键；需手动添加key binding、确保英文输入法、重启编辑器，并检查项目中setup.cfg等配置文件对docstring风格的覆盖。

AutoDocstring插件装完为啥按 Ctrl+Shift+2 没反应？

多数人卡在这一步：插件已安装，但快捷键无效。根本原因是 Sublime Text 默认没绑定该快捷键，或者当前光标不在函数/类定义行——AutoDocstring 只在光标位于 def 或 class 行首时才激活。

• 确认光标位置：必须停在 def my_func(): 这一行的任意位置（不能在函数体里）
• 检查快捷键绑定：打开 Preferences → Key Bindings，确保有类似这段配置（没有就手动加）：

  [{"keys": ["ctrl+shift+2"], "command": "auto_docstring"}]

• 别用中文输入法：中英文切换状态会导致快捷键失效，尤其 Windows 下常见
• 重启 Sublime：插件安装后有时需重启才能加载命令

生成的 docstring 格式不对，比如 Google 风格变成 NumPy 风格？

默认生成的是 Google 风格，但插件会读取项目根目录下的 .editorconfig 或 setup.cfg 中的配置，优先级高于插件设置。如果你的项目里有 setup.cfg 且含 [docstring] style = numpy，那就会强制走 NumPy 格式。

• 临时切换：调出命令面板（Ctrl+Shift+P），输入 AutoDocstring: Select Docstring Style，选你需要的格式
• 全局固定：在 Preferences → Package Settings → AutoDocstring → Settings 里写入：

  {"docstring_type": "google"}

• 注意变量名拼写："docstring_type" 不是 "style"，填错就无效

参数类型提示没自动补全，或返回值类型错了？

AutoDocstring 本身不解析类型注解，它只根据函数签名里的参数名和 return 关键字粗略推断，不会读取 def func(x: int) -> str: 中的类型提示。

python-pro

高级 Python 特性、异步编程、性能调优、静态类型、内存管理、Python 内部机制及生态库方面的专家。

下载

• 想让类型出现在 docstring 里，得手动加上类型注解，再触发生成——插件会把 x: int 解析成 Args: x (int)
• 如果函数没写 return 语句，插件默认不写 Returns:；写了但没明确返回值（比如只有 return），它会标成 None
• 遇到 *args、**kwargs，插件会原样写进 Args:，但不会展开其内部结构

生成后缩进错乱或换行异常？

这通常和 Sublime 的 tab 设置或文件编码有关。插件生成的 docstring 使用空格缩进，但如果你的文件用 tab 缩进且 detect_indentation 开启，Sublime 可能混用 tab 和空格。

立即学习“Python免费学习笔记（深入）”；

• 统一缩进：打开 View → Indentation → Convert Indentation to Spaces
• 关掉自动探测：在 Preferences → Settings 里设 "detect_indentation": false，避免干扰
• UTF-8 BOM 文件会破坏解析：保存时选 File → Save with Encoding → UTF-8（不含 BOM）

实际用起来最常被忽略的是光标位置和项目级配置文件的影响——很多人反复重装插件，其实问题就在当前文件夹里躺着一个不起眼的 setup.cfg。