用途
revise-docstrings 是一项用于审查和改进 Python docstring 的技能,目标是让 API 文档在 Great Docs 生成的参考站点中正确、完整地渲染。该技能适用于维护 Python 包公开 API 的开发者,帮助统一文档风格、补全缺失章节并排查渲染问题。
主要能力
- 审查 docstring 的完整性,对照清单逐个检查公开符号。
- 在 NumPy 与 Google 两种风格之间转换,或按已有风格补写。
- 补全缺失的参数说明、返回值说明和异常说明。
- 为函数添加可运行的示例(Quarto 代码单元或
>>>提示符)。 - 使用
%seealso指令为相关符号添加交叉引用链接。 - 使用
%nodoc指令隐藏内部符号。 - 排查常见渲染问题,如参数不显示、代码块不渲染、类型不匹配告警等。
技能目录包含 SKILL.md 以及 references/docstring-checklist.md 和 references/style-examples.md 两个参考文件。
使用方式
快速开始命令:
# Preview what Great Docs will document
great-docs scan --verbose
# Build and check the rendered reference
great-docs build && great-docs preview
在配置文件 great-docs.yml 中通过 parser: numpy 或 parser: google 指定解析风格,两种格式渲染输出一致。
从零编写 docstring 的流程:先写一行命令式摘要;必要时补充扩展摘要;记录每个参数;记录返回值;可能抛出异常时添加 Raises;添加含 Quarto 代码单元(推荐)或 >>> 提示符的 Examples 章节,可执行单元用 {python},仅展示用 {.python};为密切相关的符号添加 %seealso。
审查整个包的流程:先运行 great-docs scan --verbose 查看所有将被文档化的符号;对每个符号对照清单检查;修正缺失或错误的章节;用 great-docs build 重新构建并在浏览器中检查渲染结果。
关键约定
Great Docs 识别的章节包括摘要、扩展摘要、Parameters/Args、Returns、Raises、Examples、Notes、See Also、Warns、References。
建议优先在函数签名中使用类型注解,Great Docs 会自动读取注解,docstring 中直接写参数名即可;若在 docstring 中写类型,会覆盖注解并带来维护风险,应保持单一事实来源。
适用场景
- 为采用 Great Docs 的 Python 包整理公开 API 文档。
- 统一团队内 docstring 风格并补全缺失信息。
- 排查 API 参考页面中的渲染异常。
限制与注意事项
- 一行摘要为必需项,缺失会导致参考页面没有描述。
- NumPy 风格要求摘要与扩展摘要之间留空行。
- 缩进必须一致(NumPy 为 4 空格,Google 为嵌套在
Args:下)。 - 同一包内不得混用两种风格,混用会导致解析失败。
%nodoc会完全隐藏符号;如需选择性地隐藏而不修改源码,可在配置中使用exclude。- 类 docstring 应写在类上而非
__init__上。 - 官方资料未提供该技能的收费、价格或平台支持等更多信息。