sublimelinter-pydocstyle不生效，先确认pydocstyle是否全局可用；需手动安装并配置linters启用、指定convention及excludes，且避免与pycodestyle规则冲突。
SublimeLinter-pydocstyle 安装失败或不生效？先确认 pydocstyle 是否已全局可用
很多用户以为装了 SublimeLinter-pydocstyle 插件就自动能检查 docstring，结果保存文件毫无反应。根本原因是：这个插件只是“调用器”，它依赖系统级的 pydocstyle 命令行工具——不是 pip 装完插件就完事。
执行以下命令验证是否就绪：
pydocstyle --version
如果报错 command not found 或 'pydocstyle' is not recognized，说明没装或没进 PATH。此时必须手动安装并确保可调用：
- 用项目虚拟环境？在该环境下运行
pip install pydocstyle，然后在 Sublime Text 中配置executable指向该环境里的pydocstyle（如/path/to/venv/bin/pydocstyle或C:\path\to\venv\Scripts\pydocstyle.exe） - 用全局 Python？直接
pip install pydocstyle，再检查which pydocstyle（macOS/Linux）或where pydocstyle（Windows）输出路径是否在系统 PATH 里 - Mac M1/M2 用户常见坑：
pydocstyle可能装在 Rosetta 环境下，而 Sublime 是原生 Apple Silicon 进程，导致找不到命令——统一用 arm64 Python 重装即可
SublimeLinter 设置里必须显式启用 pydocstyle 并指定检查范围
即使 pydocstyle 命令可用，SublimeLinter 默认也不会对 .py 文件启用它。需要在 SublimeLinter 的用户设置（Preferences → Package Settings → SublimeLinter → Settings）中补全配置：
{
"linters": {
"pydocstyle": {
"enabled": true,
"args": ["--convention=numpy"], // 或 "google", "pep257"
"excludes": ["*/migrations/*", "*/tests/*"]
}
},
"syntax_map": {
"python": "python"
}
}
关键点：
-
"enabled": true必须显式写上，否则 linter 会跳过 -
"args"里传参比在命令行直接跑更严格：不支持--add-select这类带等号的写法，得拆成["--add-select", "D100"] -
"excludes"路径用 Unix 风格斜杠，Windows 上也别用反斜杠——SublimeLinter 内部统一处理为正斜杠匹配 - 如果项目用的是
numpy或google风格而非默认pep257，不配--convention就会大量误报
文档字符串被跳过检查？检查是否触发了 linter 的“最小长度阈值”
写了 """Return the user's full name.""" 却没任何提示？不是插件坏了，是 pydocstyle 默认只检查含“描述性内容”的 docstring——单行短注释、空行开头、纯参数说明都可能被忽略。
典型静默场景：
- 函数只有
"""Do something."""——pydocstyle认为太模糊，不报D200（没有首句描述） - class docstring 以空行开头：
"""Represents a user."""—— 触发D212，但默认不启用该规则 - 用了
@property或@staticmethod，但没写 docstring ——pydocstyle不检查无 docstring 的函数，只检查写了但格式不对的
解决方法：在 linter 的 "args" 中加入 --match='.*\.py'（确保扫描所有 .py）和 --add-ignore=D105（若想强制检查 getter 方法），或直接加 --add-select=D100,D101,D102 显式启用基础规则。
与其它 linter（如 flake8、pycodestyle）共存时规则冲突怎么办
同一个文件同时开启 pycodestyle 和 pydocstyle 很常见，但它们对 docstring 的要求可能打架。比如：
-
pycodestyle要求空行前后缩进一致，而pydocstyle对空行位置更敏感 -
pydocstyle报D205（docstring 在多行时需空行分隔），但flake8可能因空行报E302（函数间需两空行） - 两者都报
D100和E301时，错误标记重叠，Sublime 状态栏只显示一个
建议做法：
- 把
pydocstyle当作 docstring 专项检查器，关掉pycodestyle的 docstring 相关规则（在其args加--ignore=E501,W503等，避开 D 类） - 用
pyproject.toml统一管理规则优先级：SublimeLinter 会读取项目根目录下的该文件，比插件配置更可靠 - 别指望一次配齐所有规则——先让
pydocstyle稳定报出D100/D202这类高频问题，再逐步放开其他规则
真正麻烦的不是配置本身，而是不同工具对“合法 docstring”的定义边界模糊。比如 """Return True if user is active.""" 在 numpy 风格里算合格，在 google 风格里可能要拆成 Summary + Returns 两段——得看团队约定，而不是工具默认值。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
