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

Novo na versão 0.6.

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

Acrescente 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 gráfico é 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 gráfico. 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 gráficos de herança.

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
digraph inheritance02ef59160f { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "docutils.parsers.rst.Directive" [URL="../../extdev/markupapi.html#docutils.parsers.rst.Directive",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Base class for reStructuredText directives."]; "sphinx.ext.inheritance_diagram.InheritanceDiagram" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="Run when the inheritance_diagram directive is first encountered."]; "sphinx.util.docutils.SphinxDirective" -> "sphinx.ext.inheritance_diagram.InheritanceDiagram" [arrowsize=0.5,style="setlinewidth(0.5)"]; "sphinx.util.docutils.SphinxDirective" [URL="../../extdev/utils.html#sphinx.util.docutils.SphinxDirective",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="A base class for Sphinx directives."]; "docutils.parsers.rst.Directive" -> "sphinx.util.docutils.SphinxDirective" [arrowsize=0.5,style="setlinewidth(0.5)"]; }

Mostrando apenas nomes de classes:

.. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
   :parts: 1
digraph inheritanceec46a4ed0d { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "Directive" [URL="../../extdev/markupapi.html#docutils.parsers.rst.Directive",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Base class for reStructuredText directives."]; "InheritanceDiagram" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="Run when the inheritance_diagram directive is first encountered."]; "SphinxDirective" -> "InheritanceDiagram" [arrowsize=0.5,style="setlinewidth(0.5)"]; "SphinxDirective" [URL="../../extdev/utils.html#sphinx.util.docutils.SphinxDirective",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="A base class for Sphinx directives."]; "Directive" -> "SphinxDirective" [arrowsize=0.5,style="setlinewidth(0.5)"]; }

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
digraph inheritance834ccf9cfa { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "ext.inheritance_diagram.InheritanceDiagram" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="Run when the inheritance_diagram directive is first encountered."]; "util.docutils.SphinxDirective" -> "ext.inheritance_diagram.InheritanceDiagram" [arrowsize=0.5,style="setlinewidth(0.5)"]; "util.docutils.SphinxDirective" [URL="../../extdev/utils.html#sphinx.util.docutils.SphinxDirective",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="A base class for Sphinx directives."]; }
class sphinx.ext.inheritance_diagram.InheritanceDiagram

The internal class that implements the inheritance-diagram directive.

Configuração

inheritance_graph_attrs

Um dicionário de atributos graphviz ``graphv 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

Um dicionário de atributos do nó 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

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

inheritance_alias

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'}