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

4 files changed, 61 insertions, 13 deletions

diff --git a/CHANGES b/CHANGES
index df21d531a..e260603e0 100644
--- a/CHANGES
+++ b/CHANGES
@@ -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,