Fix docs of inheritance-diagram "parts" option

The documentation now correctly describes the behavior of the ``parts``
option in an inheritance-diagram directive: it gives the number of parts
that are *kept* not dropped. The option now also accepts negative
values, which drops parts from the left (which is the what the
documentation incorrectly claimed the option would do for positive
values)

As a form of testing of the new functionality, the documentation for the
inheritance_diagram extension now includes a section "Examples" that
demonstrate the different possibilities. This would fail to build
without the patch.

Closes #4872

CHANGES

@@ -33,6 +33,7 @@ Bugs fixed
 * #2155: Support ``code`` directive
 * C++, fix parsing of braced initializers.
 * #6172: AttributeError is raised for old styled index nodes
+* #4872: ext.inheritance_diagram: correctly describe behavior of ``parts`` option in docs, allow negative values.
 
 Testing
 --------

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

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.)
+   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.
 
-   It also supports a ``private-bases`` flag option; if given, private base
+   .. 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
 -------------
 

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.
+        *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.
+        *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,