sphinx.ext.inheritance_diagram – Inclure les diagrammes d’héritage

Added in version 0.6.

Cette extension vous permet d’inclure des diagrammes d’héritage, rendus via l’extension <sphinx.ext.graphviz>`.

Il ajoute cette directive :

.. inheritance-diagram::

Cette directive a un ou plusieurs arguments, chacun donnant un nom de module ou de classe. Les noms de classes peuvent être non qualifiés ; dans ce cas, ils sont considérés comme existant dans le module actuellement décrit (voir py:module).

Pour chaque classe donnée, et chaque classe dans chaque module donné, les classes de base sont déterminées. Ensuite, à partir de toutes les classes et de leurs classes de base, un graphique est généré qui est ensuite rendu par l’extension graphviz en un graphique vectoriel.

This directive supports an option called parts that, if given, must be an integer, advising the directive to keep that many dot-separated parts in the displayed names (from right to left). For example, parts=1 will only display class names, without the names of the modules that contain them.

Modifié dans la version 2.0: The value of for parts can also be negative, indicating how many parts to drop from the left. For example, if all your class names start with lib., you can give :parts: -1 to remove that prefix from the displayed node names.

The directive also supports a private-bases flag option; if given, private base classes (those whose name starts with _) will be included.

Vous pouvez utiliser l’option caption pour donner une légende au diagramme.

Modifié dans la version 1.1: Ajout de l’option private-bases ; auparavant, toutes les bases étaient toujours incluses.

Modifié dans la version 1.5: Ajouté l’option caption

It also supports a top-classes option which requires one or more class names separated by comma. If specified inheritance traversal will stop at the specified class names. Given the following Python module:

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

If you have specified a module in the inheritance diagram like this:

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

any base classes which are ancestors to top-classes and are also defined in the same module will be rendered as stand alone nodes. In this example class A will be rendered as stand alone node in the graph. This is a known issue due to how this extension works internally.

If you don’t want class A (or any other ancestors) to be visible then specify only the classes you would like to generate the diagram for like this:

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

Modifié dans la version 1.7: Added top-classes option to limit the scope of inheritance graphs.

Exemples

The following are different inheritance diagrams for the internal InheritanceDiagram class that implements the directive.

With full names:

.. 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)"]; }

Showing class names only:

.. 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)"]; }

Stopping the diagram at sphinx.util.docutils.SphinxDirective (the highest superclass still part of Sphinx), and dropping the common left-most part (sphinx) from all names:

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

Configuration

inheritance_graph_attrs

A dictionary of graphviz graph attributes for inheritance diagrams.

Pas exemple:

inheritance_graph_attrs = dict(rankdir="LR", size='"6.0, 8.0"',
                               fontsize=14, ratio='compress')

inheritance_node_attrs

A dictionary of graphviz node attributes for inheritance diagrams.

Pas exemple:

inheritance_node_attrs = dict(shape='ellipse', fontsize=14, height=0.75,
                              color='dodgerblue1', style='filled')

inheritance_edge_attrs

A dictionary of graphviz edge attributes for inheritance diagrams.

inheritance_alias

Allows mapping the full qualified name of the class to custom values (useful when exposing the underlying path of a class is not desirable, e.g. it’s a private class and should not be instantiated by the user).

Pas exemple:

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