开发 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
5
6from sphinx.ext.autodoc import ClassDocumenter, Documenter, 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: Documenter
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    ) -> None:
25        super().add_content(more_content)
26
27        source_name = self.get_sourcename()
28        enum_object: IntEnum = self.object
29        use_hex = self.options.hex
30        self.add_line('', source_name)
31
32        for the_member_name, enum_member in enum_object.__members__.items():  # type: ignore[attr-defined]
33            the_member_value = enum_member.value
34            if use_hex:
35                the_member_value = hex(the_member_value)
36
37            self.add_line(f'**{the_member_name}**: {the_member_value}', source_name)
38            self.add_line('', source_name)

新类的重要属性

objtype

此属性确定 auto 指令名称。在这种情况下，自动指令将是 autointenum。

directivetype

此属性设置生成的指令名称。在此示例中，生成的指令将是 .. :py:class::。

priority

数字越大，优先级越高。我们希望我们的文档器比父级具有更高的优先级。

option_spec

选项规格。我们复制父类的选项并添加一个新选项 hex。

重写的成员

can_document_member

此成员很重要，需要重写。当传入的对象可以由此类文档时，它应该返回 True。

add_directive_header

此方法生成指令头。我们添加 :final: 指令选项。请记住调用 super，否则不会生成任何指令。

add_content

此方法生成类文档的正文。调用 super 方法后，我们为枚举描述生成行。

使用扩展

您现在可以使用新的 autodoc 指令来文档任何 IntEnum。

例如，您有以下 IntEnum

my_enums.py
class Colors(IntEnum):
    """Colors enumerator"""
    NONE = 0
    RED = 1
    GREEN = 2
    BLUE = 3

这将是带有自动文档指令的文档文件

index.rst
.. autointenum:: my_enums.Colors

延伸阅读

如果您希望在多个项目或与他人共享您的扩展，请查看第三方扩展部分。