sphinx.ext.inheritance_diagram – Include inheritance diagrams
sphinx.ext.inheritance_diagram – Include inheritance diagrams
New in version 0.6.
This extension allows you to include inheritance diagrams, rendered via the Graphviz extension.
It adds this directive:
- .. inheritance-diagram::
This directive has one or more arguments, each giving a module or class name. Class names can be unqualified; in that case they are taken to exist in the currently described module (see py:module).
For each given class, and each class in each given module, the base classes are determined. Then, from all classes and their base classes, a graph is generated which is then rendered via the graphviz extension to a directed graph.
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.Changed in 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 withlib.
, 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.You can use
caption
option to give a caption to the diagram.Changed in version 1.1: Added
private-bases
option; previously, all bases were always included.Changed in version 1.5: Added
caption
optionIt 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
Changed in version 1.7: Added
top-classes
option to limit the scope of inheritance graphs.
Examples
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
[[../File:../../_images/inheritance-39fdfc4d2ad315fae27b524e58b749a5d1a927f7|class=inheritance graphviz|Inheritance diagram of sphinx.ext.inheritance_diagram.InheritanceDiagram]]
Showing class names only:
.. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
:parts: 1
[[../File:../../_images/inheritance-1caee545bc016bf9545d78116ba2be0d6321ca99|class=inheritance graphviz|Inheritance diagram of sphinx.ext.inheritance_diagram.InheritanceDiagram]]
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
[[../File:../../_images/inheritance-866c0604955b28f0b20a28fafad69147ec359651|class=inheritance graphviz|Inheritance diagram of sphinx.ext.inheritance_diagram.InheritanceDiagram]]
Configuration
- inheritance_graph_attrs
A dictionary of graphviz graph attributes for inheritance diagrams.
For example:
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.
For example:
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).
For example:
inheritance_alias = {'_pytest.Magic': 'pytest.Magic'}