diff options
| -rw-r--r-- | CHANGES | 1 | ||||
| -rw-r--r-- | doc/conf.py | 2 | ||||
| -rw-r--r-- | doc/usage/extensions/inheritance.rst | 53 | ||||
| -rw-r--r-- | sphinx/ext/inheritance_diagram.py | 18 |
4 files changed, 61 insertions, 13 deletions
@@ -69,6 +69,7 @@ Bugs fixed * AssertionError is raised when custom ``citation_reference`` node having classes attribute refers missing citation (refs: #6147) * #2155: Support ``code`` directive +* #4872: ext.inheritance_diagram: correctly describe behavior of ``parts`` option in docs, allow negative values. Testing -------- diff --git a/doc/conf.py b/doc/conf.py index 58cbfe708..f29180f77 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -7,7 +7,7 @@ import sphinx extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', 'sphinx.ext.autosummary', 'sphinx.ext.extlinks', - 'sphinx.ext.viewcode'] + 'sphinx.ext.viewcode', 'sphinx.ext.inheritance_diagram'] master_doc = 'contents' templates_path = ['_templates'] diff --git a/doc/usage/extensions/inheritance.rst b/doc/usage/extensions/inheritance.rst index c66f4130f..8e98b0bc1 100644 --- a/doc/usage/extensions/inheritance.rst +++ b/doc/usage/extensions/inheritance.rst @@ -25,12 +25,18 @@ It adds this directive: graph. This directive supports an option called ``parts`` that, if given, must be an - integer, advising the directive to remove that many parts of module names - from the displayed names. (For example, if all your class names start with - ``lib.``, you can give ``:parts: 1`` to remove that prefix from the displayed - node names.) - - It also supports a ``private-bases`` flag option; if given, private base + 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. + + .. versionchanged:: 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. You can use ``caption`` option to give a caption to the diagram. @@ -92,6 +98,41 @@ It adds this directive: 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 + +.. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram + + +Showing class names only:: + + .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram + :parts: 1 + +.. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram + :parts: 1 + +Stopping the diagram at :class:`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 + +.. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram + :top-classes: sphinx.util.docutils.SphinxDirective + :parts: -1 + + + Configuration ------------- diff --git a/sphinx/ext/inheritance_diagram.py b/sphinx/ext/inheritance_diagram.py index cfdac4803..df3ff01ed 100644 --- a/sphinx/ext/inheritance_diagram.py +++ b/sphinx/ext/inheritance_diagram.py @@ -167,11 +167,17 @@ class InheritanceGraph: """Return name and bases for all classes that are ancestors of *classes*. - *parts* gives the number of dotted name parts that is removed from the - displayed node names. - - *top_classes* gives the name(s) of the top most ancestor class to traverse - to. Multiple names can be specified separated by comma. + *parts* gives the number of dotted name parts to include in the + displayed node names, from right to left. If given as a negative, the + number of parts to drop from the left. A value of 0 displays the full + dotted name. E.g. ``sphinx.ext.inheritance_diagram.InheritanceGraph`` + with ``parts=2`` or ``parts=-2`` gets displayed as + ``inheritance_diagram.InheritanceGraph``, and as + ``ext.inheritance_diagram.InheritanceGraph`` with ``parts=3`` or + ``parts=-1``. + + *top_classes* gives the name(s) of the top most ancestor class to + traverse to. Multiple names can be specified separated by comma. """ all_classes = {} py_builtins = vars(builtins).values() @@ -332,7 +338,7 @@ class InheritanceDiagram(SphinxDirective): optional_arguments = 0 final_argument_whitespace = True option_spec = { - 'parts': directives.nonnegative_int, + 'parts': int, 'private-bases': directives.flag, 'caption': directives.unchanged, 'top-classes': directives.unchanged_required, |