文档开发工具【免费下载链接】sphinxThe Sphinx documentation generator项目地址https://gitcode.com/gh_mirrors/sp/sphinx点击查看免费下载本文以 Sphinx 官方文档 doc/usage/domains/python.rst 为主体结合仓库源码 sphinx/domains/python/init.py 与 tests/test_domains/test_domain_py.py系统讲解 Python 域domain名称py提供的全部指令、角色、签名语法与交叉引用解析机制。读完本文你将能够为任意 Python 项目编写结构完整、可交叉引用、可生成模块索引的 API 文档并理解 Sphinx 内部是如何解析这些标记的。Sphinx 中的domain是一组用于描述并链接同类对象的标记集合指令 directive 与角色 role名字形如domain:name。Python 域从 Sphinx 1.0 起提供versionadded: 1.0是 Sphinx 内置的最基础、最常用的域甚至在没有指定其他默认域时Sphinx 会默认使用 Python 域见 doc/usage/domains/index.rst 中的说明。域的概览与跨语言域体系可参考 doc/usage/domains/index.rst。模块级指令py:module与py:currentmodule.. py:module:: name该指令标记一个模块或包的子模块此时名字必须完整限定、包含包名描述的开始。模块的描述内容如 docstring可以写在指令体内——这一能力自 Sphinx 5.2 起支持versionchanged: 5.2源码中PyModule声明了has_content True并通过parse_content_to_nodes(allow_section_headingsTrue)解析指令体。该指令还会在**全局模块索引Global Module Index**中产生一条条目。从源码 sphinx/domains/python/init.py 的PyModule.run()可以看到指令执行时会将模块名写入环境上下文self.env.ref_context[py:module]使后续所有对象指令默认归属该模块调用domain.note_module(...)与domain.note_object(...)登记模块信息synopsis、platform、deprecated追加索引节点addnodes.index(entries[(pair, module; modname, ...)])。支持以下选项选项类型说明platform: platforms逗号分隔列表指明模块可用的平台若所有平台均可用则省略。key 为短标识符常用取值如IRIX、Mac、Windows、Unix应尽量复用已有 key。synopsis: purpose文本用一句话描述模块用途目前仅用于全局模块索引。deprecated无参数将模块标记为已弃用在各处显示为 Deprecated。synopsis与platform不会直接打印在文档中源码注释明确说明 the platform and synopsis arent printed; in fact, they are only used in the modindex currently——它们仅用于模块索引。而PythonModuleIndex.generate()会把synopsis显示为描述、platform显示为附加信息、deprecated显示为 Deprecated 限定词。.. py:currentmodule:: name与py:module类似它同样告诉 Sphinx从这里开始的类、函数等属于给定模块但不会创建索引条目、全局模块索引条目也不会为py:mod角色提供链接目标。适用场景同一模块的文档分散在多个文件或章节中时只在一个位置写py:module其他位置用py:currentmodule。源码实现PyCurrentModule.run()非常简单仅把py:module写入或弹出env.ref_context当参数为None时弹出不产生任何输出节点。这印证了它只改上下文、不做任何渲染的语义。对象描述指令全景Python 域为模块与类的内容提供如下指令均继承自sphinx/domains/python/_object.py中的PyObject基类即 docutils 的ObjectDescription。它们多数支持公共选项no-index、no-index-entry、no-contents-entry、no-typesetting详见 doc/usage/domains/index.rst 的 Basic Markup 小节以及module、canonical、single-line-parameter-list、single-line-type-parameter-list等。py:function模块级函数.. py:function:: Timer.repeat(repeat3, number1_000_000) .. py:function:: addT - T签名应包含参数及可选的类型参数书写方式与 Python 函数定义一致详见下文Python 签名语法。注意方法请使用py:method而非py:function。描述正文通常应包含参数要求与用法尤其是作为参数传入的可变对象是否会被修改、副作用与可能的异常这些信息也可以用结构化形式给出见下文信息字段列表。py:function支持的选项选项类型说明引入版本async无值标记为异步函数渲染时在签名前加async关键字2.1canonical完整限定名含模块名当对象从其他模块导入时指明其真正的定义位置4.0module文本指明对象定义位置默认取py:currentmodule指定的模块—single-line-parameter-list无值强制参数在单逻辑行输出覆盖python_maximum_signature_line_length与maximum_signature_line_length7.1single-line-type-parameter-list无值强制类型参数在单逻辑行输出覆盖上述两个长度配置7.1源码中PyFunction.option_spec在基类基础上追加了async选项get_signature_prefix()会在检测到async时向签名插入desc_sig_keyword(, async)节点。同时PyFunction.add_target_and_index()会为函数生成形如f() (in module m)的索引条目。py:data模块级数据与定义常量描述模块中的全局数据包括变量与被当作定义常量的值。建议类型别名用py:type类变量与实例属性用py:attribute。支持选项源码PyVariable追加了type与value两个directives.unchanged选项type: type of the variable2.4 起将按 Python 表达式解析以生成类型注解的交叉引用。参数必须是合法的annotation expression。注意:type:指令选项与:type:信息字段的语法不同指令选项不理解 reStructuredText 标记也不理解or/of关键字——联合类型必须用|序列类型必须用方括号也不能使用:ref:... 这类角色。value: initial value of the variable2.4 起变量的初始值。canonical4.0 起对象从其他模块导入时指明定义位置。module默认取py:currentmodule。源码中PyVariable.handle_signature()会按序把type注解_parse_annotation(typ, self.env)与value渲染为name: type value形式的签名。py:exception异常类.. py:exception:: name .. py:exception:: name(parameters) .. py:exception:: nametype parameters描述异常类。签名可以但不必带构造参数的圆括号也可以按 PEP 695 带类型参数。选项选项类型说明引入版本final无值标记为 final 类渲染final关键字3.1module文本定义位置默认取py:currentmodule—single-line-parameter-list无值参见py:class同名选项7.1single-line-type-parameter-list无值参见py:class同名选项7.1py:exception与py:class在源码中共享同一个PyClasslike实现directives表中两者都映射到PyClasslike其get_signature_prefix()会依次渲染final、abstract关键字与对象类型名class/exception。py:class类.. py:class:: name .. py:class:: name(parameters) .. py:class:: nametype parameters签名可选包含类型参数PEP 695或带参数的圆括号显示为构造参数。属于该类的成员应写在指令体内若写在类外则名字必须包含类名以保证交叉引用仍能工作。官方推荐第一种写法.. py:class:: Foo .. py:method:: quux() -- or -- .. py:class:: Bar .. py:method:: Bar.quux()选项选项类型说明引入版本abstract无值标记为抽象基类渲染abstract关键字8.2canonical完整限定名从其他模块导入时的真实定义位置4.0final无值标记为 final 类渲染final关键字3.1module文本定义位置默认取py:currentmodule—single-line-parameter-list无值强制构造参数单逻辑行输出7.1single-line-type-parameter-list无值强制类型参数单逻辑行输出7.1PyClasslike的allow_nesting True这就是类体内能嵌套py:method等指令的机制基础。py:attribute对象数据属性描述对象的数据属性。描述应包含期望的数据类型以及它是否可被直接修改类型别名请用py:type文档化。选项与py:data一致type2.4 起作为 annotation expression 解析生成交叉引用语法注意事项同上、value2.4 起、canonical4.0 起、module。源码PyAttribute与PyVariable的渲染逻辑一致只是索引文本分别显示为attr (cls attribute)与data (in module)。py:property对象属性描述对象的 property4.0 起提供源码PyProperty。选项选项类型说明引入版本abstract/abstractmethod无值标记为抽象属性渲染abstract关键字8.2 起支持:abstract:别名8.2别名classmethod无值标记为类方法 property渲染class关键字4.2type文本作为 annotation expression 解析以生成类型注解交叉引用—module文本定义位置默认取py:currentmodule—官方示例.. py:property:: Cheese.amount_in_stock :no-index: :abstractmethod: Cheese levels at the *National Cheese Emporium*.py:type类型别名描述类型别名type alias。别名所代表的真实类型应通过canonical选项描述指令支持可选描述正文7.4 起.. py:type:: UInt64 Represent a 64-bit positive integer.canonical选项示例.. py:type:: StrPattern :canonical: str | re.Pattern[str] Represent a regular expression or a compiled pattern.渲染时canonical会以name canonical形式显示在签名中源码PyTypeAlias.handle_signature()通过_parse_annotation生成可交叉引用的注解节点且py:type指令会在签名前加type关键字前缀。PyTypeAlias.get_index_text()生成的索引文本为name (type alias in module.Class)。py:method及其变体.. py:method:: name(parameters) .. py:method:: nametype parameters描述对象方法。参数不应包含self。描述内容与py:function类似。选项选项类型说明引入版本abstract/abstractmethod无值标记抽象方法渲染abstractmethod关键字8.2 起支持:abstract:别名2.1 / 8.2async无值标记异步方法渲染async关键字2.1canonical完整限定名从其他模块导入时的真实定义位置4.0classmethod无值标记类方法渲染classmethod关键字2.1final无值标记 final 方法渲染final关键字3.1module文本定义位置默认取py:currentmodule—single-line-parameter-list无值强制参数单逻辑行输出7.1single-line-type-parameter-list无值强制类型参数单逻辑行输出7.2staticmethod无值标记静态方法渲染static关键字2.1源码PyMethod.get_signature_prefix()会按final、abstract、async、classmethod、staticmethod的顺序在签名前插入对应关键字节点。索引文本据此生成meth() (cls class method)/(cls static method)/(cls method)。另外三个便捷指令.. py:staticmethod:: name(parameters)/nametype parameters0.4 起等价于带:staticmethod:的py:method。源码中PyStaticMethod.run()直接改写为py:method并设置self.options[staticmethod] True。.. py:classmethod:: name(parameters)/nametype parameters0.6 起等价于带:classmethod:的py:method。.. py:decorator:: name/name(parameters)/nametype parameters描述装饰器函数。签名应表示其作为装饰器的用法而不是其作为普通函数的入参。例如def removename(func): func.__name__ return func def setnewname(name): def decorator(func): func.__name__ name return func return decorator对应的描述应为.. py:decorator:: removename Remove name of the decorated function. .. py:decorator:: setnewname(name) Set name of the decorated function to *name*.而不是.. py:decorator:: removename(func)。引用装饰器使用py:deco角色。源码PyDecoratorFunction会把self.name改写为py:function并在签名开头插入节点desc_addname(, )。.. py:decoratormethod:: name/name(signature)/nametype parameters同py:decorator但用于作为方法的装饰器同样用py:deco角色引用。源码PyDecoratorMethod同样插入前缀。Python 签名语法函数、方法、类构造器的签名可以直接按 Python 语法书写支持默认值、仅位置参数positional-only、仅关键字参数keyword-only、类型注解与类型参数。例如.. py:function:: compile(source: str, filename: Path, symbol: str file) - ast.AST可选参数的多签名写法对于没有默认值的可选参数典型场景是没有关键字参数支持的 C 扩展模块函数可以在同一个指令中列出同一签名的多个版本.. py:function:: compile(source) compile(source, filename) compile(source, filename, symbol)另一种写法是用方括号标记可选部分习惯上将左方括号放在逗号前[,.. py:function:: compile(source[, filename[, symbol]])类型参数PEP 695Python 3.12 引入了直接在类或函数定义中声明的类型参数type parametersclass AnimalListAnimalT: ... def addT - T: return a b对应的 reStructuredText 标记为.. py:class:: AnimalList[AnimalT] .. py:function:: addT - T细节与完整规范参见 PEP 695 与 PEP 696。实现层面sphinx/domains/python/_object.py中的py_sig_re正则负责拆分签名依次匹配可选的类名前缀[\w.]*\.、对象名\w、可选的类型参数列表\[...\]、可选的参数列表(...)与可选的返回注解- ...参数与类型参数列表的解析在 sphinx/domains/python/_annotations.py 的_parse_arglist/_parse_type_list中完成支持*、/分隔符与 PEP 695 约束/默认值。信息字段列表Info field lists在任意py对象描述指令体内以下 reStructuredText 字段列表field list会被识别并格式化0.4 起提供3.0 起新增meta字段字段名用途param,parameter,arg,argument,key,keyword参数说明type参数类型尽可能生成链接raises,raise,except,exception说明抛出的异常及抛出时机var,ivar,cvar变量说明vartype变量类型尽可能生成链接returns,return返回值说明rtype返回类型尽可能生成链接meta为对象描述添加元数据元数据不会显示在输出文档中。例如:meta private:表示该对象是私有成员被sphinx.ext.autodoc用于成员过滤注意在当前版本中var、ivar、cvar均显示为 Variable三者没有区别。字段名必须由上述关键字之一加一个参数组成returns与rtype例外不需要参数。完整示例.. py:function:: send_message(sender, recipient, message_body, [priority1]) Send a message to a recipient :param str sender: The person sending the message :param str recipient: The recipient of the message :param str message_body: The body of the message :param priority: The priority of the message, can be a number 1-5 :type priority: int or None :return: the message id :rtype: int :raises ValueError: if the message_body exceeds 160 characters :raises TypeError: if the message_body is not a basestring如果类型是单个单词也可以合并类型与描述:param int priority: The priority of the message, can be a number 1-5该合并写法自 1.5 起支持。容器类型自动链接1.5 起列表、字典等容器类型可用以下语法自动生成链接方括号与圆括号两种写法均可:type priorities: list(int) :type priorities: list[int] :type mapping: dict(str, int) :type mapping: dict[str, int] :type point: tuple(float, float) :type point: tuple[float, float]多类型自动链接类型字段中由竖线|或单词or分隔的多个类型会自动链接:type an_arg: int or None :vartype a_var: str or int :rtype: float or str :type an_arg: int | None :vartype a_var: str | int :rtype: float | str实现上_object.py的PyXrefMixin.make_xrefs()通过_delimiters_re正则按[](),、or、|、...等分隔符把类型字符串拆成多个子目标逐个生成交叉引用节点。而filter_meta_fields()注册于object-description-transform事件会在文档树构建阶段剔除:meta:字段使元数据不进入输出。交叉引用 Python 对象以下角色role引用模块中的对象并在找到匹配标识符时尽可能生成超链接角色引用对象说明py:mod模块可用点分名也可用于包名—py:funcPython 函数可用点分名角色文本无需带尾随圆括号以增强可读性当配置值add_function_parentheses为True默认时 Sphinx 会自动补上py:decoPython 装饰器可用点分名渲染输出会前置如:py:deco:removename 显示为removename。实现上_PyDecoXRefRole.process_link()对标题统一加上前缀py:data模块级变量—py:const定义常量不打算被修改的变量—py:class类可用点分名—py:meth对象方法角色文本可包含类型名与方法名若位于某个类型描述内部类型名可省略可用点分名py:attr对象数据属性该角色也能引用 property源码resolve_xref中对attr类型会回退到meth/_prop查找py:type类型别名—py:exc异常可用点分名—py:obj任意类型的对象适合用作default_role等场景0.4 起目标规格Target specification引用目标可以指定为完整限定名如:py:meth:my_module.MyClass.my_method或任意缩短版本如 :py:meth:MyClass.my_method、:py:meth:my_method。同时可应用通用的交叉引用修饰符见 doc/usage/domains/index.rst 的 Cross-referencing syntax显式标题与目标:py:mod:mathematical functions 会引用math模块但链接文本为 mathematical functions。内容以感叹号!为前缀不创建引用/超链接。内容以~为前缀链接文本只显示目标的最后一段。例如:py:meth:~queue.Queue.get 引用queue.Queue.get但只显示get。实现上PyXRefRole.process_link()会剥离标题的.前缀仅对目标有意义、剥离目标的~前缀仅对标题有意义并将点前缀转换为refspecific标记。目标解析Target resolution给定的链接目标名按以下策略解析为对象源码PythonDomain.find_obj()与resolve_xref()角色中的名字先不加任何限定搜索然后加当前模块名前缀搜索再加当前模块与类名若有前缀搜索。若名字以点.为前缀则顺序反转先尝试模块.类.名字、模块.名字最后才是不限定搜索。例如在 Pythoncodecs模块的文档中:py:func:open总是指向内置函数而 :py:func:.open指向codecs.open。类似的启发式也用于判断名字是否为当前文档类的属性。此外若名字带点前缀且未找到精确匹配则把目标当作后缀在所有以该后缀结尾的对象名中搜索。例如:py:meth:.TarFile.close 即使当前模块不是tarfile也能引用tarfile.TarFile.close()。由于这可能有歧义当存在多个匹配时 Sphinx 会给出警告resolve_xref()中输出more than one target found for cross-reference。~与.前缀可以组合:py:meth:~.TarFile.close 引用tarfile.TarFile.close()但可见链接标题只有close()。find_obj()还会跳过尾随的()name.removesuffix(())因此:py:func:compile() 也能解析。此外resolve_xref()内置了几组回退策略class引用解析失败时回退到data/attr兼容类型别名被文档化为 data/attr 但按 class 引用的写法相关测试见tests/test_domains/test_domain_py.py的test_type_alias_xref_resolutionattr回退到meth、meth回退到内部_prop角色保证旧文档中:attr:/:meth:与py:property互相兼容。相关配置项围绕 Python 域Sphinx 提供以下配置项均定义于 doc/usage/configuration.rst并在PythonDomain.setup()中注册配置项默认值说明add_function_parenthesesTrue是否在函数与方法角色文本如:func:input后自动追加圆括号modindex_common_prefix[]排序 Python 模块索引时忽略的前缀列表。例如设为[foo.]后foo.bar会显示在字母 B 下而非 F 下适合单个包组成的项目。注意目前仅对 HTML builder 生效0.6 起python_display_short_literal_typesFalse控制typing.Literal类型的显示方式False时按标准语法显示Literal[egg, spam]True时按 PEP 604 风格的短语法显示egg | spam6.2 起python_maximum_signature_line_lengthNone签名长度字符数超过该值时签名中每个参数单独一行显示None表示无上限、整个签名单行显示。这是域级设置覆盖全局的maximum_signature_line_length。对 Python 域长度计算取决于格式化的是类型参数还是参数列表前者忽略参数列表长度后者忽略类型参数列表长度。例如设为20时addT: VERY_LONG_SUPER_TYPE, U: VERY_LONG_SUPER_TYPE的类型参数会换行而参数列表保持单行7.1 起python_trailing_comma_in_multi_line_signaturesTrue跨多行的参数列表末尾是否使用尾随逗号8.2 起python_use_unqualified_type_namesFalse若能解析抑制 Python 引用中的模块名显示4.0 起实验性功能这些配置在源码 sphinx/domains/python/init.py 的setup()中通过app.add_config_value(...)注册均标记为env重建级别。python_use_unqualified_type_names的显示逻辑位于_object.py的PyXrefMixin.make_xref()开启时目标短名target.rpartition(.)[-1]会作为已解析条件的显示文本。测试覆盖见tests/test_domains/test_domain_py.py的test_python_python_use_unqualified_type_names、test_domain_py_python_maximum_signature_line_length_in_html与test_domain_py_python_trailing_comma_in_multi_line_signatures_in_html。从源码看 Python 域的完整实现PythonDomainsphinx/domains/python/init.py是整个 Python 域的核心类其关键成员name py、label Pythonobject_types将 12 种对象类型function、data、class、exception、method、classmethod、staticmethod、attribute、property、type、module 等映射到可引用它们的角色如class同时可被class、exc、obj角色引用directives注册function、data、class、exception、method、classmethod、staticmethod、attribute、property、type、module、currentmodule、decorator、decoratormethod共 14 个指令roles注册data、exc、func、deco、class、const、attr、type、meth、mod、obj共 11 个角色其中func、meth使用fix_parensTrue即自动补圆括号indices提供PythonModuleIndex本地名 Python Module Indexshortname modules即全局模块索引数据模型objects全限定名 →ObjectEntry(docname, node_id, objtype, aliased)与modules模块名 →ModuleEntry(docname, node_id, synopsis, platform, deprecated)并实现note_object/note_module/clear_doc/merge_domaindata以支持增量构建与并行读写find_obj()上文所述的目标解析策略核心resolve_xref()/resolve_any_xref()交叉引用解析与:any:角色支持resolve_any_xref始终以refspecific模式搜索并跳过重复的别名匹配get_objects()向全文搜索索引提供对象别名条目priority-1不可全文搜索普通条目priority1。此外setup()还通过missing-reference事件注册了builtin_resolver对py域中指向内置类如None、内置类型与typing模块类名的引用不发出 nitpicky 警告。ObjectEntry/ModuleEntry的重复定义会在构建时给出duplicate object description警告提示使用:no-index:抑制其中一个。Python 域是 Sphinx 默认的域未配置primary_domain时了解它的指令、签名与解析机制是编写高质量 Python API 文档、理解 autodoc 输出结构乃至开发第三方 domain 的基础。赞分享文档开发工具【免费下载链接】sphinxThe Sphinx documentation generator项目地址https://gitcode.com/gh_mirrors/sp/sphinx点击查看免费下载相关推荐ONNX Runtime CUDA MatMulNBits 算子深度解析权重量化矩阵乘的分派链路、GEMV 内核与 fpA_intB 路径ONNX Runtime CUDA MatMulNBits 算子深度解析权重量化矩阵乘的分派链路、GEMV 内核与 fpA_intB 路径 导读 本文基于 O文档开发工具Pydantic AI 贡献指南用 complete-partial-pr 技能把不完整 PR 补全为可维护的集成合约Pydantic AI 贡献指南用 complete partial pr 技能把不完整 PR 补全为可维护的集成合约 本文讲解 Pydantic AI 仓库文档开发工具PyTorch Docstring 编写规范详解从签名行到 Sphinx 交叉引用的完整指南PyTorch Docstring 编写规范详解从签名行到 Sphinx 交叉引用的完整指南 本文基于 PyTorch 仓库中的文档字符串写作技能指南 .c人工智能机器学习深度学习分布式训练模型编译上一篇前端离线应用Service Worker在Must-Watch JavaScript的演讲下一篇免费AI视频放大神器5分钟将模糊视频无损升级到4K超高清画质创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
