为IntEnum开发AutoDoc扩展

本教程的目标是创建一个扩展，添加对AutoDoc新类型的支持。此AutoDoc扩展名将格式化 IntEnum 类来自于Python标准库。(模块 enum )

概述

我们想要的扩展将创建IntEnum的自动文档。 IntEnum 是标准库中的整数枚举类 enum 模块。

目前，此类没有特殊的自动文档行为。

我们希望在AutoDoc中添加以下内容：

  • 一种新的 autointenum 指令，它将记录 IntEnum 班级。

  • 生成的文档将包含所有可能的枚举值和名称。

  • 这个 autointenum 指令将有一个选项 :hex: 这将导致以十六进制形式打印整数。

先决条件

我们需要与中相同的设置 the previous extensions 。这一次，我们将在一个名为 autodoc_intenum.py 。这个 my_enums.py 将包含我们将记录的示例枚举。

下面是您可能获得的文件夹结构示例：

└── source
    ├── _ext
    │   └── autodoc_intenum.py
    ├── conf.py
    ├── index.rst
    └── my_enums.py

正在写入扩展名

开始于 setup 函数用于扩展。

1def setup(app: Sphinx) -> None:
2    app.setup_extension('sphinx.ext.autodoc')  # Require autodoc extension
3    app.add_autodocumenter(IntEnumDocumenter)

这个 setup_extension() 方法将拉出AutoDoc扩展，因为我们的新扩展依赖于AutoDoc。 add_autodocumenter() 是注册新的AUTO文档管理器类的方法。

我们希望从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

有几个不同的文档管理器类，例如 MethodDocumenter 或 AttributeDocumenter 在AutoDoc扩展中可用，但我们的新类是 ClassDocumenter AutoDoc使用哪个Documenter类来对类进行文档记录。

这是我们新的自动文档管理器类的定义：

 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

此方法生成类文档的主体。在调用超方法之后，我们生成用于枚举描述的行。

使用扩展名

现在，您可以使用新的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