如何用Ruff禁用D100/C0111及忽略Sphinx文档字符串特定告警

问题场景 #

使用Sphinx时，Python文件顶部采用如下格式的文档字符串：

#!/usr/bin/env python
# -*- coding: utf-8 -*-

"""
my-module
=========
Some notes about my module
"""

会触发两个Ruff告警：

• D205：摘要行与描述间需空一行
• D400：首行需以句号结尾

调整格式会破坏Sphinx生成的标题样式，且不想在标题后加句号，需要仅忽略该场景的这两个告警。此外，在project.toml中配置ignore = ["D100"]无效果，无法禁用D100（缺少模块文档字符串告警）和C0111（缺少函数/类文档字符串告警），同时疑惑忽略D100是否会阻止文件顶部的文档字符串检查。

解决方案 #

1. 忽略特定场景的D205、D400告警 #

如果只想针对该文件的文档字符串忽略这两个规则，有两种方式：

• 文件级注释忽略：在文档字符串上方添加注释，指定忽略规则

  #!/usr/bin/env python
  # -*- coding: utf-8 -*-
  # ruff: noqa: D205,D400
  
  """
  my-module
  =========
  Some notes about my module
  """
  

• 配置文件指定文件忽略：在project.toml中添加per-file-ignores配置，针对目标文件忽略规则

  [tool.ruff.lint.per-file-ignores]
  "your_module.py" = ["D205", "D400"]
  

2. 解决D100、C0111禁用无效问题 #

确保project.toml的配置格式正确，以下是两种配置方式：

• 全局忽略：对所有文件禁用这两个规则

  [tool.ruff.lint]
  ignore = ["D100", "C0111"]
  

• 指定文件忽略：仅对特定文件禁用

  [tool.ruff.lint.per-file-ignores]
  "target_file.py" = ["D100", "C0111"]
  

注意：检查Ruff版本，旧版本可能存在配置解析问题，建议升级到最新稳定版。

3. D100规则的作用说明 #

忽略D100仅会阻止Ruff告警“Missing docstring in public module”（缺少模块级文档字符串），但不会影响其他文档字符串格式类规则（如D205、D400）的检查。如果需要忽略格式规则，仍需单独指定对应的规则码。

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