sphinx.ext.inheritance_diagram – Inclui diagramas de herança

Adicionado na versão 0.6.

Esta extensão permite incluir diagramas de herança, renderizados através da extensão Graphviz.

Acrescenta esta diretiva:

.. inheritance-diagram::

Esta diretiva possui um ou mais argumentos, cada um dando um nome de módulo ou classe. Nomes de classes podem ser desqualificados; Nesse caso, eles são levados a existir no módulo descrito atualmente (consulte py:module).

Para cada classe fornecida e cada classe em cada módulo fornecido, as classes base são determinadas. Então, de todas as classes e suas classes base, um grafo é gerado, o qual é então renderizado através da extensão graphviz para um grafo direcionado.

Essa diretiva suporta uma opção chamada parts que, se fornecida, deve ser um inteiro, aconselhando a diretiva a manter tantas partes separadas por pontos nos nomes exibidos (da direita para a esquerda). Por exemplo, parts=1 exibirá apenas nomes de classes, sem os nomes dos módulos que os contêm.

Alterado na versão 2.0: O valor de parts também pode ser negativo, indicando quantas partes devem ser descartadas da esquerda. Por exemplo, se todos os nomes de classes começarem com lib., você poderá fornecer :parts: -1 para remover esse prefixo dos nomes de nós exibidos.

A diretiva também suporta uma opção de flag private-base; se dado, classes de base privadas (aquelas cujo nome começa com _) serão incluídas.

Você pode usar a opção caption para dar uma legenda ao diagrama.

Alterado na versão 1.1: Adicionado a opção private-bases; anteriormente, todas as bases eram sempre incluídas.

Alterado na versão 1.5: Adicionado a opção caption

Ele também suporta uma opção top-classes que requer um ou mais nomes de classes separados por vírgula. Se o percurso de herança especificado for interrompido nos nomes das classes especificadas. Dado o seguinte módulo 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

Se você especificou um módulo no diagrama de herança assim:

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

quaisquer classes base que sejam ancestrais de top-classes e também estejam definidas no mesmo módulo serão renderizadas como nós independentes. Neste exemplo, a classe A será renderizada como nó independente no grafo. Esse é um problema conhecido devido a como essa extensão funciona internamente.

Se você não quiser que a classe A (ou qualquer outro ancestral) esteja visível, especifique apenas as classes para as quais você gostaria de gerar o diagrama:

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

Alterado na versão 1.7: Adicionado a opção top-classes para limitar o escopo de grafos de herança.

:include-subclasses: (no value)

Adicionado na versão 8.2.

Se fornecido, qualquer subclasse das classes também será adicionada ao diagrama.

Dado o módulo Python acima, você pode especificar seu diagrama de herança assim:

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

Isso incluirá as classes A, B, C, D, E e F no diagrama de herança, mas nenhuma outra classe no módulo dummy.test.

Exemplos

A seguir estão os diferentes diagramas de herança para a classe interna InheritanceDiagram que implementa a diretiva.

Com nomes completos:

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

Mostrando apenas nomes de classes:

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

Parando o diagrama em sphinx.util.docutils.SphinxDirective (a maior superclasse ainda parte do Sphinx), e soltando a parte mais comum à esquerda (sphinx) de todos os nomes:

.. 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

A classe interna que implementa a diretiva inheritance-diagram.

Configuração

inheritance_graph_attrs
Type:
dict[str, str | int | float | bool]
Default:
{}

Um dicionário de atributos de grafo do graphviz para diagramas de herança.

Por exemplo:

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

Um dicionário de atributos do nó de graphviz para diagramas de herança.

Por exemplo:

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

Um dicionário de atributos de borda do graphviz para diagramas de herança.

inheritance_alias
Type:
dict[str, str]
Default:
{}

Permite mapear o nome completo qualificado da classe para valores personalizados (útil quando a exposição do path subjacente de uma classe não é desejável, por exemplo, é uma classe privada e não deve ser instanciada pelo usuário).

Por exemplo:

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