Manim 社区 Docstring 编写规范从 NumPy 格式到类型注解的完整实践指南【免费下载链接】manimA community-maintained Python framework for creating mathematical animations.项目地址: https://gitcode.com/GitHub_Trending/man/manim导读本文以 Manim Community 官方贡献指南中的 docstrings.rst 为骨架系统讲解 Manim 项目如何编写高效、正确、可被 Sphinx 自动提取为 API 文档的 docstring——包括三重引号排版约定、NumPy 格式的各章节Parameters/Attributes/Returns/Examples书写规则、varargs 与Other Parameters的用法并结合 manim/typing.py、mypy.ini 与 conf.py 等仓库源码说明这些规范在真实代码中的落地形态。读完本文你将掌握一套可直接套用于任何 Python 库的、面向 Sphinx autodoc Napoleon 生态的文档编写方法论并理解 Manim 文档背后docstring 即文档源的工程化机制。一、Docstring 在 Manim 文档体系中的位置Docstring 是紧跟在模块、函数、类或方法定义之后的一个字符串字面量用于记录代码的行为。Manim 官方文档中的大量 API 参考页面本质上并不是单独维护的.rst文本而是由 Sphinx 的autodoc扩展在构建文档时导入 Manim 源码、提取其中的 docstring 自动生成的。这一点在 docs/source/contributing/docs.rst 中有明确说明Manim 使用 Sphinx 构建文档并依赖autodoc从源码提取 docstring、autosummary自动为类、方法、属性、函数生成文档页、Graphviz渲染继承图和Napoleon让 Sphinx 能解析 NumPy 风格的 docstring。构建配置位于 docs/source/conf.py其中extensions列表包含了上述全部扩展。因此写 docstring 就是写文档。一篇格式错误或不完整的 docstring会直接影响 API 参考页面的生成质量。这也解释了为什么 Manim 社区将 docstring 规范作为独立文档页进行约束。二、基本排版约定三重引号后同行开始描述规范要求类的描述文字必须和开头的三个引号位于同一行而不是换行缩进后再开始。def do_this(): This is correct. (...) def dont_do_this(): This is incorrect. (...) 这一约定的实际效果在源码中随处可见。例如 manim/mobject/mobject.py 中Mobject类的 docstring 第一行直接接在之后class Mobject: Mathematical Object: base class for objects that can be displayed on screen. ... 保持一致的行内开头格式能让 autodoc 提取出来的首行摘要干净利落也便于后续作为短描述在索引页中展示。三、NumPy 格式Manim 文档的唯一标准Manim Community 明确规定文档使用NumPy 格式详细格式说明可参考 numpydoc 官方 format 文档。核心要素包括以下四类3.1Attributes类的全部属性必须在类 docstring 中列出所有类可能拥有的属性都必须写在Attributes章节并附带简短或按需加长的描述。同时有一条容易被忽略的规则__init__的参数要写在类 docstring 的Parameters章节中而不是写在__init__自己的 docstring 下。如果参数与属性完全一致例如 dataclass 场景Parameters可以省略此时Attributes章节必须始终存在除非类没有任何属性。仓库中的真实示例见 manim/mobject/mobject.py 中Mobject类的 docstringclass Mobject: Mathematical Object: base class for objects that can be displayed on screen. ... Attributes ---------- submobjects : List[:class:Mobject] The contained objects. points : :class:numpy.ndarray The points of the objects. .. seealso:: :class:~.VMobject conf.py中的autoclass_content both见 docs/source/conf.py意味着类文档会同时包含类 docstring 与__init__的 docstring 内容因此把__init__参数写进类 docstring 并不会造成信息丢失反而能聚合到同页展示。文档给出的标准写法示例class MyClass: My cool class. Long or short (whatever is more appropriate) description here. Parameters ---------- name The classs name. id The classs id. mobj The mobject linked to this instance. Defaults to Mobject() \ (is set to that if None is specified). Attributes ---------- name The users name. id The users id. singleton Something. mobj The mobject linked to this instance. def __init__(name: str, id: int, singleton: MyClass, mobj: Mobject None): ...注意示例中的反斜杠续行\用于在 reST 源码中拼接较长的参数描述渲染时不会产生多余换行。3.2Parameters函数参数的文档化规则在函数上使用Parameters说明每个参数的作用。要点包括函数没有参数时Parameters章节应当省略不要在参数的类型标注type annotation上写默认值——文档渲染时函数签名上已经展示了默认值这与autodoc_typehints description的设置相配合类型会以描述形式呈现在文档中如果确实需要说明省略该参数时的后果或想强调默认行为必须写在该参数的描述文字里而不是类型里。真实代码示例manim/mobject/mobject.py 中Mobject.add相关方法def add(self, *mobjects): Add mobjects as submobjects. The mobjects are added to :attr:submobjects. ... Parameters ---------- mobjects The mobjects to add. Returns ------- :class:Mobject self Raises ------ :class:ValueError When a mobject tries to add itself. 这里还展示了 NumPy 格式中另外两个允许的章节Returns与Raises后文详述Returns。varargs 与Other Parameters当函数接收*args/**kwargs时规范要求逐一列出每个值可能出现的类型而不是笼统写 args: 参数列表Parameters ---------- args The args specified can be either an int or a float. kwargs The kwargs specified can only be a float.如果**kwargs只接受某些特定名字的键值对则应把这些具名项放进Other Parameters章节单独描述Other Parameters ---------------- kwarg_param_1 Parameter documentation here (etc)3.3Returns返回值类型与含义用Returns说明函数返回值的类型和具体返回内容。以下情况可以省略该章节函数从不显式return即总是返回None且为什么该函数不返回值非常清楚。除此之外都应写明Returns。看一个仓库中的典型写法manim/mobject/mobject.py 中Mobject._assert_valid_submobjects_internal的兄弟方法 docstringReturns ------- :class:Mobject The Mobject itself.3.4Examples强烈鼓励为每个函数提供使用示例规范高度鼓励为函数编写Examples章节——原则上每个函数都应有除非其用法极其显然这本身是个可讨论的判断。即便用法明显添加示例也能给文档用户更好的指引。Python 代码示例用::字面块呈现def my_function( thing: int, other: np.ndarray, name: str, *, d: SomeClassFromFarAway, test: Optional[int] 45 ) - EpicClassInThisFile: # typings are optional for now My cool function. Builds and modifies an :class:EpicClassInThisFile instance with the given parameters. Parameters ---------- thing Specifies the index of life. other Specifies something cool. name Specifies my name. d Sets thing D to this value. test Defines the number of times things should be tested. \ Defaults to 45, because that is almost the meaning of life. Returns ------- :class:EpicClassInThisFile The generated EpicClass with the specified attributes and modifications. Examples -------- Normal usage:: my_function(5, np.array([1, 2, 3]), Chelovek, dSomeClassFromFarAway(coolTrue), test5) # code... pass此外还有两条与示例强相关的补充规则动画/视频相关的改动尽可能附带演示用的 GIF 或视频方便读者直观看到效果交互引用docstring 中可以使用 Sphinx 交叉引用语法如:class:、:meth:、:attr:、:func:、:mod:让文档页面之间形成可跳转的链接。这一能力由conf.py中的 autodoc、Napoleon 与autodoc_type_aliases等配置共同支撑。四、可验证的落地案例Manim 源码中的 docstring 实践上面的规则并非纸上谈兵。通过搜索源码可以确认Manim 自身严格遵循了这些约定类级Attributesmanim/mobject/mobject.py 的Mobject类 docstring 中写明了submobjects、points等属性函数级Parameters/Returns/RaisesMobject的多个方法如add、_assert_valid_submobjects_internal、animation_override_for等的 docstring 均包含完整的Parameters、Returns必要时还有Raises例如animation_override_for的Returns写明返回Optional[Callable[[Mobject, ...], Animation]]并说明返回None时的语义Return类型描述优先于字面签名源码中Returns使用:class:Mobject 这类带交叉引用的描述而不是简单的裸类型名这正是尽可能显式的体现。值得一提的工程细节是 manim/typing.py 模块——它本身就是docstring 即文档的极致案例。文件开头有一段给开发者的 admonition源码中形如[CATEGORY]的字符串标记会被自动解析将下方定义的类型别名归类到对应分类如Primitive data types、Color types、Point types、Vector types、Matrix types、Bézier types、Function types、Text mobject types、Image types、Path types。这些类型别名及其 docstring 由 conf.py 中调用的parse_module_attributes()解析并注入autodoc_type_aliases最终成为 API 参考页的组成部分。五、从 docstring 到类型注解Manim 的配套规范docstring 规范与类型注解规范是配套的。虽然本文主体是 docstring但关联文档所服务的文档体系中类型提示type hints直接影响了 docstring 中Parameters/Returns的写法例如默认值写在签名而非类型里这一规则的前提就是签名本身带有类型注解。因此简要梳理 Manim 的配套约定详见 typings.rst 与 types.rst5.1 类型检查工具链Manim 使用mypy对代码库做类型检查配置集中在 mypy.inifiles manim、python_version 3.11启用了disallow_untyped_defs、disallow_untyped_calls、disallow_incomplete_defs等严格选项同时为部分尚未完全类型化的模块设置了ignore_errors True过渡为使用最低支持 Python 版本尚不具备的新特性可借助typing_extensions使用新的联合类型语法x | y与内建泛型下标时应引入from __future__ import annotations关键准则包括无返回值函数含__init__标注- None路径类变量使用StrPath/StrOrBytesPath*args/**kwargs不可留空通常用Any按 PEP 484 数字塔用float而非int | float用x | y取代Union[x, y]泛型必须参数化list[int]、type[Any]需要同一类型关联时用TypeVar返回self时用typing_extensions.Self仅用于类型提示的导入放在if TYPE_CHECKING:块内。5.2 类型别名的使用哲学Like后缀types.rst 给出了核心规则参数类型尽可能宽返回类型尽可能具体。因此面向用户的函数应当接受Like类型如Point3DLike可以是 NumPy 数组或 float 元组/列表而返回非Like的 NumPy 类型如Point3D。direction/axis类参数应使用VectorND/VectorNDLike颜色参数使用ParsableManimColorBézier 相关数据使用BezierPoints/BezierPath/Spline及其二次、三次变体图像像素数据使用PixelArray区别于PIL.Image.Image。这些别名在 manim/typing.py 中都有详细定义与 docstring如Point3DLike: TypeAlias Point3D | tuple[float, float, float]并注明shape: (3,)读者可直接打开该文件查阅全部清单。六、文档构建与本地预览了解规范后可以在本地构建文档验证效果进入docs/目录Windows 执行./make.bat htmlmacOS 与 Linux 执行make html首次构建需要数分钟需要从零解析并生成全部.rst内容后续增量构建会明显加快相关说明见 docs/source/contributing/docs.rst。注意事项浏览器缓存可能导致示例页面显示旧版本此时清除缓存或使用无痕窗口本地构建场景下必要时清空docs/source/references目录再重建详见 examples.rst若在 docstring 中编写带.. manim::指令的场景示例构建时会被识别并由当前版本 Manim 实际渲染相关指令实现位于 manim/utils/docbuild/manim_directive.py文档构建的完整扩展、主题Furo与国际化配置可参考 docs/source/conf.py 与 docs/source/index.rst。七、实践检查清单在提交 docstring 相关改动前可以对照以下清单自检描述文字是否与开头的同行类是声明了Attributes章节并列出全部属性__init__参数是否写在类 docstring 的Parameters中dataclass 场景优先Attributes函数有参数时是否写了Parameters且默认值只出现在参数描述里而非类型里*args/**kwargs是否逐一列出了可能的类型具名 kwargs 是否放进了Other Parameters非None返回值的函数是否写了Returns是否为函数补充了Examples示例动画相关改动附上 GIF/视频描述是否尽可能显式是否利用了:class:/:meth:/:attr:等交叉引用让文档互联将 docstring 视为一等公民的工程文化正是 Manim 能够保持数万行 API 文档与源码同步演进的根基。对任何希望用 Sphinx Napoleon 体系构建高质量文档的 Python 项目而言这套规范都值得直接借鉴。【免费下载链接】manimA community-maintained Python framework for creating mathematical animations.项目地址: https://gitcode.com/GitHub_Trending/man/manim创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Manim 社区 Docstring 编写规范：从 NumPy 格式到类型注解的完整实践指南
Manim 社区 Docstring 编写规范从 NumPy 格式到类型注解的完整实践指南【免费下载链接】manimA community-maintained Python framework for creating mathematical animations.项目地址: https://gitcode.com/GitHub_Trending/man/manim导读本文以 Manim Community 官方贡献指南中的 docstrings.rst 为骨架系统讲解 Manim 项目如何编写高效、正确、可被 Sphinx 自动提取为 API 文档的 docstring——包括三重引号排版约定、NumPy 格式的各章节Parameters/Attributes/Returns/Examples书写规则、varargs 与Other Parameters的用法并结合 manim/typing.py、mypy.ini 与 conf.py 等仓库源码说明这些规范在真实代码中的落地形态。读完本文你将掌握一套可直接套用于任何 Python 库的、面向 Sphinx autodoc Napoleon 生态的文档编写方法论并理解 Manim 文档背后docstring 即文档源的工程化机制。一、Docstring 在 Manim 文档体系中的位置Docstring 是紧跟在模块、函数、类或方法定义之后的一个字符串字面量用于记录代码的行为。Manim 官方文档中的大量 API 参考页面本质上并不是单独维护的.rst文本而是由 Sphinx 的autodoc扩展在构建文档时导入 Manim 源码、提取其中的 docstring 自动生成的。这一点在 docs/source/contributing/docs.rst 中有明确说明Manim 使用 Sphinx 构建文档并依赖autodoc从源码提取 docstring、autosummary自动为类、方法、属性、函数生成文档页、Graphviz渲染继承图和Napoleon让 Sphinx 能解析 NumPy 风格的 docstring。构建配置位于 docs/source/conf.py其中extensions列表包含了上述全部扩展。因此写 docstring 就是写文档。一篇格式错误或不完整的 docstring会直接影响 API 参考页面的生成质量。这也解释了为什么 Manim 社区将 docstring 规范作为独立文档页进行约束。二、基本排版约定三重引号后同行开始描述规范要求类的描述文字必须和开头的三个引号位于同一行而不是换行缩进后再开始。def do_this(): This is correct. (...) def dont_do_this(): This is incorrect. (...) 这一约定的实际效果在源码中随处可见。例如 manim/mobject/mobject.py 中Mobject类的 docstring 第一行直接接在之后class Mobject: Mathematical Object: base class for objects that can be displayed on screen. ... 保持一致的行内开头格式能让 autodoc 提取出来的首行摘要干净利落也便于后续作为短描述在索引页中展示。三、NumPy 格式Manim 文档的唯一标准Manim Community 明确规定文档使用NumPy 格式详细格式说明可参考 numpydoc 官方 format 文档。核心要素包括以下四类3.1Attributes类的全部属性必须在类 docstring 中列出所有类可能拥有的属性都必须写在Attributes章节并附带简短或按需加长的描述。同时有一条容易被忽略的规则__init__的参数要写在类 docstring 的Parameters章节中而不是写在__init__自己的 docstring 下。如果参数与属性完全一致例如 dataclass 场景Parameters可以省略此时Attributes章节必须始终存在除非类没有任何属性。仓库中的真实示例见 manim/mobject/mobject.py 中Mobject类的 docstringclass Mobject: Mathematical Object: base class for objects that can be displayed on screen. ... Attributes ---------- submobjects : List[:class:Mobject] The contained objects. points : :class:numpy.ndarray The points of the objects. .. seealso:: :class:~.VMobject conf.py中的autoclass_content both见 docs/source/conf.py意味着类文档会同时包含类 docstring 与__init__的 docstring 内容因此把__init__参数写进类 docstring 并不会造成信息丢失反而能聚合到同页展示。文档给出的标准写法示例class MyClass: My cool class. Long or short (whatever is more appropriate) description here. Parameters ---------- name The classs name. id The classs id. mobj The mobject linked to this instance. Defaults to Mobject() \ (is set to that if None is specified). Attributes ---------- name The users name. id The users id. singleton Something. mobj The mobject linked to this instance. def __init__(name: str, id: int, singleton: MyClass, mobj: Mobject None): ...注意示例中的反斜杠续行\用于在 reST 源码中拼接较长的参数描述渲染时不会产生多余换行。3.2Parameters函数参数的文档化规则在函数上使用Parameters说明每个参数的作用。要点包括函数没有参数时Parameters章节应当省略不要在参数的类型标注type annotation上写默认值——文档渲染时函数签名上已经展示了默认值这与autodoc_typehints description的设置相配合类型会以描述形式呈现在文档中如果确实需要说明省略该参数时的后果或想强调默认行为必须写在该参数的描述文字里而不是类型里。真实代码示例manim/mobject/mobject.py 中Mobject.add相关方法def add(self, *mobjects): Add mobjects as submobjects. The mobjects are added to :attr:submobjects. ... Parameters ---------- mobjects The mobjects to add. Returns ------- :class:Mobject self Raises ------ :class:ValueError When a mobject tries to add itself. 这里还展示了 NumPy 格式中另外两个允许的章节Returns与Raises后文详述Returns。varargs 与Other Parameters当函数接收*args/**kwargs时规范要求逐一列出每个值可能出现的类型而不是笼统写 args: 参数列表Parameters ---------- args The args specified can be either an int or a float. kwargs The kwargs specified can only be a float.如果**kwargs只接受某些特定名字的键值对则应把这些具名项放进Other Parameters章节单独描述Other Parameters ---------------- kwarg_param_1 Parameter documentation here (etc)3.3Returns返回值类型与含义用Returns说明函数返回值的类型和具体返回内容。以下情况可以省略该章节函数从不显式return即总是返回None且为什么该函数不返回值非常清楚。除此之外都应写明Returns。看一个仓库中的典型写法manim/mobject/mobject.py 中Mobject._assert_valid_submobjects_internal的兄弟方法 docstringReturns ------- :class:Mobject The Mobject itself.3.4Examples强烈鼓励为每个函数提供使用示例规范高度鼓励为函数编写Examples章节——原则上每个函数都应有除非其用法极其显然这本身是个可讨论的判断。即便用法明显添加示例也能给文档用户更好的指引。Python 代码示例用::字面块呈现def my_function( thing: int, other: np.ndarray, name: str, *, d: SomeClassFromFarAway, test: Optional[int] 45 ) - EpicClassInThisFile: # typings are optional for now My cool function. Builds and modifies an :class:EpicClassInThisFile instance with the given parameters. Parameters ---------- thing Specifies the index of life. other Specifies something cool. name Specifies my name. d Sets thing D to this value. test Defines the number of times things should be tested. \ Defaults to 45, because that is almost the meaning of life. Returns ------- :class:EpicClassInThisFile The generated EpicClass with the specified attributes and modifications. Examples -------- Normal usage:: my_function(5, np.array([1, 2, 3]), Chelovek, dSomeClassFromFarAway(coolTrue), test5) # code... pass此外还有两条与示例强相关的补充规则动画/视频相关的改动尽可能附带演示用的 GIF 或视频方便读者直观看到效果交互引用docstring 中可以使用 Sphinx 交叉引用语法如:class:、:meth:、:attr:、:func:、:mod:让文档页面之间形成可跳转的链接。这一能力由conf.py中的 autodoc、Napoleon 与autodoc_type_aliases等配置共同支撑。四、可验证的落地案例Manim 源码中的 docstring 实践上面的规则并非纸上谈兵。通过搜索源码可以确认Manim 自身严格遵循了这些约定类级Attributesmanim/mobject/mobject.py 的Mobject类 docstring 中写明了submobjects、points等属性函数级Parameters/Returns/RaisesMobject的多个方法如add、_assert_valid_submobjects_internal、animation_override_for等的 docstring 均包含完整的Parameters、Returns必要时还有Raises例如animation_override_for的Returns写明返回Optional[Callable[[Mobject, ...], Animation]]并说明返回None时的语义Return类型描述优先于字面签名源码中Returns使用:class:Mobject 这类带交叉引用的描述而不是简单的裸类型名这正是尽可能显式的体现。值得一提的工程细节是 manim/typing.py 模块——它本身就是docstring 即文档的极致案例。文件开头有一段给开发者的 admonition源码中形如[CATEGORY]的字符串标记会被自动解析将下方定义的类型别名归类到对应分类如Primitive data types、Color types、Point types、Vector types、Matrix types、Bézier types、Function types、Text mobject types、Image types、Path types。这些类型别名及其 docstring 由 conf.py 中调用的parse_module_attributes()解析并注入autodoc_type_aliases最终成为 API 参考页的组成部分。五、从 docstring 到类型注解Manim 的配套规范docstring 规范与类型注解规范是配套的。虽然本文主体是 docstring但关联文档所服务的文档体系中类型提示type hints直接影响了 docstring 中Parameters/Returns的写法例如默认值写在签名而非类型里这一规则的前提就是签名本身带有类型注解。因此简要梳理 Manim 的配套约定详见 typings.rst 与 types.rst5.1 类型检查工具链Manim 使用mypy对代码库做类型检查配置集中在 mypy.inifiles manim、python_version 3.11启用了disallow_untyped_defs、disallow_untyped_calls、disallow_incomplete_defs等严格选项同时为部分尚未完全类型化的模块设置了ignore_errors True过渡为使用最低支持 Python 版本尚不具备的新特性可借助typing_extensions使用新的联合类型语法x | y与内建泛型下标时应引入from __future__ import annotations关键准则包括无返回值函数含__init__标注- None路径类变量使用StrPath/StrOrBytesPath*args/**kwargs不可留空通常用Any按 PEP 484 数字塔用float而非int | float用x | y取代Union[x, y]泛型必须参数化list[int]、type[Any]需要同一类型关联时用TypeVar返回self时用typing_extensions.Self仅用于类型提示的导入放在if TYPE_CHECKING:块内。5.2 类型别名的使用哲学Like后缀types.rst 给出了核心规则参数类型尽可能宽返回类型尽可能具体。因此面向用户的函数应当接受Like类型如Point3DLike可以是 NumPy 数组或 float 元组/列表而返回非Like的 NumPy 类型如Point3D。direction/axis类参数应使用VectorND/VectorNDLike颜色参数使用ParsableManimColorBézier 相关数据使用BezierPoints/BezierPath/Spline及其二次、三次变体图像像素数据使用PixelArray区别于PIL.Image.Image。这些别名在 manim/typing.py 中都有详细定义与 docstring如Point3DLike: TypeAlias Point3D | tuple[float, float, float]并注明shape: (3,)读者可直接打开该文件查阅全部清单。六、文档构建与本地预览了解规范后可以在本地构建文档验证效果进入docs/目录Windows 执行./make.bat htmlmacOS 与 Linux 执行make html首次构建需要数分钟需要从零解析并生成全部.rst内容后续增量构建会明显加快相关说明见 docs/source/contributing/docs.rst。注意事项浏览器缓存可能导致示例页面显示旧版本此时清除缓存或使用无痕窗口本地构建场景下必要时清空docs/source/references目录再重建详见 examples.rst若在 docstring 中编写带.. manim::指令的场景示例构建时会被识别并由当前版本 Manim 实际渲染相关指令实现位于 manim/utils/docbuild/manim_directive.py文档构建的完整扩展、主题Furo与国际化配置可参考 docs/source/conf.py 与 docs/source/index.rst。七、实践检查清单在提交 docstring 相关改动前可以对照以下清单自检描述文字是否与开头的同行类是声明了Attributes章节并列出全部属性__init__参数是否写在类 docstring 的Parameters中dataclass 场景优先Attributes函数有参数时是否写了Parameters且默认值只出现在参数描述里而非类型里*args/**kwargs是否逐一列出了可能的类型具名 kwargs 是否放进了Other Parameters非None返回值的函数是否写了Returns是否为函数补充了Examples示例动画相关改动附上 GIF/视频描述是否尽可能显式是否利用了:class:/:meth:/:attr:等交叉引用让文档互联将 docstring 视为一等公民的工程文化正是 Manim 能够保持数万行 API 文档与源码同步演进的根基。对任何希望用 Sphinx Napoleon 体系构建高质量文档的 Python 项目而言这套规范都值得直接借鉴。【免费下载链接】manimA community-maintained Python framework for creating mathematical animations.项目地址: https://gitcode.com/GitHub_Trending/man/manim创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考