claude-skills 的 Python Docstrings 实战指南Google / NumPy / Sphinx 三种规范速查与工程化落地【免费下载链接】claude-skills67 Specialized Skills for Full-Stack Developers. Transform Claude Code into your expert pair programmer.项目地址: https://gitcode.com/GitHub_Trending/claud/claude-skills本文基于 claude-skills 仓库中 code-documenter 技能的专项参考文档 skills/code-documenter/references/python-docstrings.md系统讲解 Python 文档字符串的三大主流书写规范Google、NumPy、Sphinx覆盖函数、类与异步场景的完整写法、各小节段落的跨风格对照以及如何在 skills/code-documenter/SKILL.md 所定义的文档化工作流中用 doctest、pydocstyle、interrogate 等工具对文档字符串进行验证与覆盖率度量。读完本文你将能为任何 Python 代码库写出风格统一、可被自动化校验、可直接生成 API 文档的 docstrings。为什么 Python 文档字符串需要一个“推荐规范”文档字符串docstring是 Python 中内建于语言层面的文档机制但语言本身并没有规定它的“排版”标准。同一个项目里如果有人用:param name:、有人用Args:、还有人只写一行摘要后续无论是 IDE 提示、静态检查还是文档生成器Sphinx、MkDocs都无法统一解析。在 claude-skills 的 code-documenter 技能体系中规范一致性被明确视为文档质量的核心要求。其 SKILL.md 的 Core Workflow 要求先询问格式偏好Discover、再识别语言与框架Detect、扫描未文档化代码Analyze、应用统一格式Document最后用工具验证示例可运行Validate。其中对 Python 的验证手段包括# 验证 doctest 块 python -m doctest file.py # 模块级全量校验 pytest --doctest-modules这意味着文档字符串不只是给人读的注释它还是可以被测试框架执行的“可运行文档”。因此选择一种规范并坚持到底是从源头保证文档质量的唯一正确做法。Google Styleclaude-skills 推荐的默认选择Google 风格是 code-documenter 参考文档中明确标注为 Recommended 的格式。它的核心特征是使用Args:、Returns:、Raises:、Example:等带冒号的块状标题可读性强、Markdown 友好、解析成本低。函数文档字符串模板def calculate_total(items: list[Item], tax_rate: float 0.0) - float: Calculate total cost including tax. Args: items: List of items to calculate total for. tax_rate: Tax rate as decimal (e.g., 0.08 for 8%). Returns: Total cost including tax. Raises: ValueError: If tax_rate is negative or items is empty. Example: calculate_total([Item(10), Item(20)], 0.1) 33.0 要点拆解第一行摘要必须是单行、以句号结尾的祈使句或陈述句说明函数“做什么”。Args每个参数一行格式为参数名: 描述类型由类型注解type hint承担不必重复写在参数名后面。可选参数在描述中说明默认值语义例如tax_rate的0.0默认值。Returns描述返回值“是什么”而不是重复函数名。Raises列出可能抛出的异常类型并说明触发条件——这是最容易漏写、但对调用方最有价值的部分。Example使用 doctest 约定前缀表示输入、下一行是期望输出。这样示例可以直接被 SKILL.md 中的python -m doctest自动验证。Google 风格与 Python 类型注解的分工参考文档的签名使用了items: list[Item]、tax_rate: float 0.0、- float这样的现代注解。在 Google 风格中类型信息来自注解描述则负责语义如“8% 的税率写作 0.08”两者分工明确、互不重复。这与仓库内脚本使用的类型风格一致——例如 scripts/validate-skills.py 中大量使用list[ValidationIssue]、dict | None等新式注解而 ruff.toml 将 target-version 设置为py311说明整个仓库以 Python 3.11 的现代语法为基准。NumPy Style面向科学计算的段落式规范NumPy 风格源于 SciPy 生态使用独立成段的小节标题和下划线装饰线。它的显著优势是每个参数独占一行、适合参数数量多或附带公式/矩阵形状说明的场景。def calculate_total(items: list[Item], tax_rate: float 0.0) - float: Calculate total cost including tax. Parameters ---------- items : list[Item] List of items to calculate total for. tax_rate : float, optional Tax rate as decimal (e.g., 0.08 for 8%). Default is 0.0. Returns ------- float Total cost including tax. Raises ------ ValueError If tax_rate is negative or items is empty. Examples -------- calculate_total([Item(10), Item(20)], 0.1) 33.0 要点拆解小节标题使用Parameters、Returns、Raises、Examples标题下用等号下划线装饰。Parameters中格式为name : type可选参数标注为name : type, optional并明确写出默认值如Default is 0.0.。Returns段中先写类型float再换行缩进写描述。Raises段同样先写异常类型再写触发条件。有多个返回值时NumPy 风格的Returns段天然支持逐行列出tuple 元素名 : 类型的结构这是它相比 Google 风格的一大优势。如果项目以数据科学、机器学习为主例如仓库中的 pandas-pro、spark-engineer 等技能所服务的领域NumPy 风格往往更贴合团队习惯因为它可以清晰地描述数组的形状约束如shape (n,)。Sphinx Style与 Sphinx 自动文档生成深度集成Sphinx 风格使用:param name:、:type name:、:returns:、:raises:等 reStructuredText 指令能被 Sphinx 的autodoc扩展原生解析适合需要发布正式 API 参考手册的项目。def calculate_total(items: list[Item], tax_rate: float 0.0) - float: Calculate total cost including tax. :param items: List of items to calculate total for. :type items: list[Item] :param tax_rate: Tax rate as decimal (e.g., 0.08 for 8%). :type tax_rate: float :returns: Total cost including tax. :rtype: float :raises ValueError: If tax_rate is negative or items is empty. .. code-block:: python calculate_total([Item(10), Item(20)], 0.1) 33.0 要点拆解param/type 成对出现:param描述语义:type声明类型。当类型由注解提供时:type可以省略但在不使用注解的旧代码库中它不可或缺。returns/rtype 成对出现:returns:描述返回值:rtype:声明返回类型。raises 语法特殊:raises ValueError: 触发条件异常类型写在指令后、冒号前。示例使用.. code-block:: python指令包裹因为 reStructuredText 本身不支持doctest 的逐行缩进约定。Sphinx 风格与文档站点生成链路契合度最高。仓库中的 site 部分就是一个基于 Astro 的文档站点而 code-documenter 技能的知识域覆盖 Docusaurus、MkDocs、VitePress、Swagger UI 等文档体系见 skills/code-documenter/SKILL.md 的 Knowledge ReferenceSphinx 风格正是为“把 docstring 直接变成 API 手册”这种流水线准备的。Class 文档从属性到构造方法的完整范式参考文档给出了一个异步服务类的完整示例其中既包含类级文档Attributes、Example也包含__init__的方法级文档Args。class UserService: Service for managing user operations. This service handles CRUD operations for users and integrates with the authentication system. Attributes: db: Database session for queries. cache: Redis client for caching. Example: service UserService(db, cache) user await service.create_user(data) def __init__(self, db: AsyncSession, cache: Redis) - None: Initialize UserService. Args: db: Database session for queries. cache: Redis client for caching. 要点拆解类级摘要后可以加一段扩展说明描述类的职责与协作对象。Attributes段落列出实例属性的语义。注意Attributes描述的是“构造后如何使用”与__init__的Args描述“构造时如何传入”是互补的两层信息。Example段落中展示异步调用await service.create_user(data)也是合法的 doctest 写法需要配合asyncio环境运行。__init__通常不需要Returns因为构造方法返回实例本身文档应聚焦在参数含义上。这套“类级 Attributes 构造方法 Args”的双层结构与 code-documenter 的文档覆盖清单见 skills/code-documenter/references/coverage-reports.md逐条对应类用途已描述、构造参数已文档化、公开方法已文档化、重要属性已解释。这也是它被选作技能参考的原因。跨风格小节对照表一份速查总纲参考文档用两张表格给出了跨风格的速查索引这是在团队混用风格时判断“该写哪个段落名”的权威依据。风格速查StyleArgs FormatReturns FormatGoogleArgs:blockReturns:blockNumPyParameterssectionReturnssectionSphinx:param name::returns:可用小节Sections对照SectionGoogleNumPySphinxParametersArgs:Parameters:param:ReturnsReturns:Returns:returns:RaisesRaises:Raises:raises:ExamplesExample:Examples.. code-block::NotesNote:Notes.. note::AttributesAttributes:Attributes:ivar:实际使用建议团队选定一种风格后所有函数和类保持一致不要在同一文件中混用。Raises/异常文档是 code-documenter 的 MUST DO 项“Document exceptions/errors”“Skip error documentation”被明确列入 MUST NOT DO三种风格下都不应省略。复杂函数务必提供Example因为 SKILL.md 的校验步骤要求“Test code examples in documentation”和“Fix examples and re-validate”。与 API 层文档的衔接docstring 如何升级为 OpenAPI 文档在 FastAPI / Django 项目中docstring 不只是函数注释它们还会被框架自动转化为 Swagger UI / OpenAPI 文档。参考文档 skills/code-documenter/references/api-docs-fastapi-django.md 展示了这条链路FastAPI从类型注解与 docstring 自动生成 OpenAPI 文档。写清Args/Raises中的语义描述配合summary、tags、response_model装饰器参数即可得到可直接访问的交互式文档/docs。例如HTTPException: 400 if email already exists.这样的 Raises 描述会进入 Swagger UI 的异常说明。Django REST Framework使用drf-spectacular的extend_schema装饰器扩展 schemadocstring 中的行为描述与serializer的help_text共同构成文档内容。因此在写 Python docstring 时遵循参考文档给出的 Google/NumPy/Sphinx 模板等于同时为“人读的注释”和“机器读的 API 规范”打下了基础——这正是 code-documenter 将 docstrings 与 OpenAPI/JSDoc 并列为其核心产出见 skills/code-documenter/SKILL.md的原因。工程化落地验证、覆盖率与风格检查文档字符串写得好不好最终要靠工具说话。综合参考文档与仓库实践推荐以下三条落地路径。1. 用 doctest 保证示例可运行SKILL.md 将“测试文档中的代码示例”列为强制步骤# 单文件 python -m doctest file.py # 整个模块/包 pytest --doctest-modules只要 docstring 中的Example块严格遵循约定就能自动回归验证。如果校验失败参考文档的要求是先修复示例再继续禁止带着错误的示例产出文档。2. 用 pydocstyle 统一风格coverage-reports.md 给出了与 docstring 直接相关的 Python 检查工具pip install pydocstyle pydocstyle --conventiongoogle src/--convention参数直接对应本文的三大风格google、numpy、sphinx选哪个与团队确定的 docstring 风格保持一致。值得一提的是claude-skills 仓库自身的 Python 脚本同样有一套风格基线ruff.toml配置了 E/W/F/I/UP/B/SIM/RUF 规则集、line-length 120、双引号风格这与 docstring 规范一道构成了“代码即文档、文档即代码”的质量文化。3. 用 interrogate 度量覆盖率pip install interrogate interrogate -v src/interrogate 会统计“有多少函数/类/方法带有 docstring”其质量分可以纳入 CI 门槛。coverage-reports.md 给出了文档覆盖率的量化基准MetricGoodAcceptablePoorFunction coverage90%70-90%70%Class coverage100%90%90%API endpoint coverage100%100%100%Example coverage50%30-50%30%可以把这些阈值写成 CI 检查低于Acceptable时报警低于Good时阻止合并。仓库的 scripts/validate-skills.py 展示了类似的自动化治理思路——它用策略模式注册了多个 checkerYAML 校验、必填字段、引用路径解析等来保证技能文档的质量与一致性docstring 覆盖率检查完全可以采用同样的持续校验机制。总结选型默认推荐 Google 风格数据科学团队可选 NumPy需要 Sphinx 自动生成 API 手册时用 Sphinx 风格。一旦选定全库统一。结构函数文档覆盖摘要、Args、Returns、Raises、Example类文档额外补充 Attributes 与__init__的参数说明。验证python -m doctest/pytest --doctest-modules验证示例pydocstyle --convention...统一风格interrogate度量覆盖率并纳入 CI。延伸docstring 是 FastAPI/Django 自动生成 OpenAPI 文档的信息来源写好它就是写好 API 文档的第一步。进一步阅读完整的方法级示例可继续查看 skills/code-documenter/SKILL.md 的 Quick-Reference Examples包含 Google 与 NumPy 风格的真实函数示例覆盖率报告模板见 skills/code-documenter/references/coverage-reports.mdAPI 场景下的文档写法见 skills/code-documenter/references/api-docs-fastapi-django.md。【免费下载链接】claude-skills67 Specialized Skills for Full-Stack Developers. Transform Claude Code into your expert pair programmer.项目地址: https://gitcode.com/GitHub_Trending/claud/claude-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考