开发 autodoc 扩展¶
本教程的目标是创建一个扩展,为 autodoc 添加对新类型支持。此 autodoc 扩展将格式化来自 Python 标准库的 IntEnum
类。(模块 enum
)
概述¶
我们希望扩展能够为 IntEnum 创建自动文档。 IntEnum
是标准库 enum
模块中的整数枚举类。
目前,此类没有特殊的自动文档行为。
我们希望为 autodoc 添加以下内容:
一个新的
autointenum
指令,用于记录IntEnum
类。生成的文档将包含所有枚举可能的值及其名称。
autointenum
指令将有一个选项:hex:
,它将导致整数以十六进制形式打印。
先决条件¶
我们需要与 之前的扩展 中相同的设置。这次,我们将扩展放在名为 autodoc_intenum.py
的文件中。 my_enums.py
将包含我们将记录的示例枚举。
以下是一个您可能获得的文件夹结构示例:
└── source
├── _ext
│ └── autodoc_intenum.py
├── conf.py
├── index.rst
└── my_enums.py
编写扩展¶
从扩展的 setup
函数开始。
1def setup(app: Sphinx) -> ExtensionMetadata:
2 app.setup_extension('sphinx.ext.autodoc') # Require autodoc extension
3 app.add_autodocumenter(IntEnumDocumenter)
4 return {
5 'version': '1',
6 'parallel_read_safe': True,
7 }
setup_extension()
方法将提取 autodoc 扩展,因为我们的新扩展依赖于 autodoc。 add_autodocumenter()
是注册我们的新自动文档生成器类的方法。
我们希望从 autodoc 扩展导入某些对象。
1from __future__ import annotations
2
3from enum import IntEnum
4from typing import TYPE_CHECKING, Any
5
6from sphinx.ext.autodoc import ClassDocumenter, bool_option
7
autodoc 扩展中提供了多种不同的文档生成器类,例如 MethodDocumenter
或 AttributeDocumenter
,但我们的新类是 ClassDocumenter
的子类,autodoc 使用该类来记录类。
这是我们新的自动文档生成器类的定义:
1class IntEnumDocumenter(ClassDocumenter):
2 objtype = 'intenum'
3 directivetype = ClassDocumenter.objtype
4 priority = 10 + ClassDocumenter.priority
5 option_spec = dict(ClassDocumenter.option_spec)
6 option_spec['hex'] = bool_option
7
8 @classmethod
9 def can_document_member(
10 cls, member: Any, membername: str, isattr: bool, parent: Any
11 ) -> bool:
12 try:
13 return issubclass(member, IntEnum)
14 except TypeError:
15 return False
16
17 def add_directive_header(self, sig: str) -> None:
18 super().add_directive_header(sig)
19 self.add_line(' :final:', self.get_sourcename())
20
21 def add_content(
22 self,
23 more_content: StringList | None,
24 no_docstring: bool = False,
25 ) -> None:
26 super().add_content(more_content, no_docstring)
27
28 source_name = self.get_sourcename()
29 enum_object: IntEnum = self.object
30 use_hex = self.options.hex
31 self.add_line('', source_name)
32
33 for the_member_name, enum_member in enum_object.__members__.items():
34 the_member_value = enum_member.value
35 if use_hex:
36 the_member_value = hex(the_member_value)
37
38 self.add_line(f'**{the_member_name}**: {the_member_value}', source_name)
39 self.add_line('', source_name)
新类的重要属性:
- objtype
此属性确定
auto
指令的名称。在这种情况下,auto 指令将为autointenum
。- directivetype
此属性设置生成的指令名称。在此示例中,生成的指令将为
.. :py:class::
。- priority
数字越大,优先级越高。我们希望我们的文档生成器比父类具有更高的优先级。
- option_spec
选项规范。我们复制父类的选项并添加一个新的选项 hex 。
重写成员
- can_document_member
重写此成员非常重要。当传递的对象可以由此类记录时,它应该返回 True 。
- add_directive_header
此方法生成指令标题。我们添加了 :final: 指令选项。请记住调用 super ,否则不会生成任何指令。
- add_content
此方法生成类文档的主体。在调用 super 方法后,我们为枚举描述生成行。
使用扩展¶
您现在可以使用新的 autodoc 指令记录任何 IntEnum
。
例如,您有以下 IntEnum
:
class Colors(IntEnum):
"""Colors enumerator"""
NONE = 0
RED = 1
GREEN = 2
BLUE = 3
这将是包含自动文档指令的文档文件:
.. autointenum:: my_enums.Colors
进一步阅读¶
如果您希望在多个项目或与他人共享您的扩展,请查看 第三方扩展 部分。