sphinx.ext.inheritance_diagram -- 包含继承关系图

在 0.6 版本加入.

此扩展允许包含用 Graphviz extension 渲染的继承关系图.

它添加了以下指令：

.. inheritance-diagram::

这个指令有一个或多个参数，每个参数都给出一个模块或类名。类名可以是非限定的；在这种情况下，它们被认为存在于当前描述的模块中（参见 py:module）。

对于每个给定的类，以及每个给定模块中的每个类，确定基类。然后，从所有类及其基类生成一个图，然后通过graphviz扩展将其呈现为有向图。

此指令支持一个名为 parts 的选项，如果给定该选项，该选项必须是一个整数，建议该指令在显示的名称中保留这些以点分隔的部分（从右到左）。例如，parts=1 将只显示类名，而不显示包含类名的模块的名称。

在 2.0 版本发生变更: parts 的值也可以是负数，表示从左边删除多少个部分。例如，如果所有类名都以 lib. 开头，则可以给 :parts:-1 从显示的节点名中删除该前缀。

该指令还支持一个 private-bases 标志选项；如果给定了该选项，则将包括私有基类（名称以 _ 开头的基类）。

您可以使用 caption 选项为图表提供标题。

在 1.1 版本发生变更: 添加了 private-bases 选项；以前，总是包含所有的基。

在 1.5 版本发生变更: 添加了 caption 选项

它还支持 顶级类 选项，该选项需要一个或多个用逗号分隔的类名。如果指定继承，则遍历将在指定的类名处停止。给定以下Python模块：

"""
       A
      / \
     B   C
    / \ / \
   E   D   F
"""

class A:
    pass

class B(A):
    pass

class C(A):
    pass

class D(B, C):
    pass

class E(B):
    pass

class F(C):
    pass

如果您在继承关系图中指定了如下模块：

.. inheritance-diagram:: dummy.test
   :top-classes: dummy.test.B, dummy.test.C

作为 顶级类 的祖先并在同一模块中定义的任何基类都将呈现为独立节点。在本例中，类A将在图中呈现为独立节点。这是一个已知的问题，因为这个扩展是如何在内部工作的。

如果不希望类A（或任何其他祖先）可见，则只指定要为其生成关系图的类，如下所示:

.. inheritance-diagram:: dummy.test.D dummy.test.E dummy.test.F
   :top-classes: dummy.test.B, dummy.test.C

在 1.7 版本发生变更: 添加了 顶级类 选项以限制继承图的范围。

:include-subclasses: (no value)

在 8.2 版本加入.

如果给定，类的任何子类也将被添加到图中。

给定上面的Python模块，您可以像这样指定您的继承关系图：

.. inheritance-diagram:: dummy.test.A
   :include-subclasses:

这将包括类A、B、C、D、E和F在继承关系图中，但不会包括模块 dummy.test 中的其他类。

实际案例

以下是实现指令的内部 InheritanceDiagram 类的不同继承关系图。

全名：

.. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
Inheritance diagram of sphinx.ext.inheritance_diagram.InheritanceDiagram

仅显示类名：

.. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
   :parts: 1
Inheritance diagram of sphinx.ext.inheritance_diagram.InheritanceDiagram

在以下位置停止关系图 sphinx.util.docutils.SphinxDirective （最高的超类仍然是Sphinx的一部分），并从所有名称中删除最左边的公共部分（sphinx）：

.. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
   :top-classes: sphinx.util.docutils.SphinxDirective
   :parts: -1
Inheritance diagram of sphinx.ext.inheritance_diagram.InheritanceDiagram
class sphinx.ext.inheritance_diagram.InheritanceDiagram

实现 inheritance-diagram 指令的内部类。

配置

inheritance_graph_attrs
类型:
dict[str, str | int | float | bool]
默认:
{}

继承图的graphviz图属性字典。

例如:

inheritance_graph_attrs = dict(rankdir="LR", size='"6.0, 8.0"',
                               fontsize=14, ratio='compress')
inheritance_node_attrs
类型:
dict[str, str | int | float | bool]
默认:
{}

继承图的graphviz节点属性字典。

例如:

inheritance_node_attrs = dict(shape='ellipse', fontsize=14, height=0.75,
                              color='dodgerblue1', style='filled')
inheritance_edge_attrs
类型:
dict[str, str | int | float | bool]
默认:
{}

graphviz节点的字典的属性是继承关系图。

inheritance_alias
类型:
dict[str, str]
默认:
{}

允许将类的完整限定名映射到自定义值（当不需要公开类的基础路径时，非常有用，例如，它是一个私有类，不应由用户实例化）。

例如:

inheritance_alias = {'_pytest.Magic': 'pytest.Magic'}