Merge pull request #6164 from goerz/inheritance_diagram

Fix docs of inheritance-diagram "parts" option

.travis.yml

@@ -37,6 +37,7 @@ matrix:
       services: xvfb
 
 install:
+  - "sudo apt-get install graphviz"
   - if [ $IS_PYTHON = true ]; then pip install -U tox codecov; fi
   - if [ $IS_PYTHON = false ]; then npm install; fi
 

CHANGES

@@ -89,6 +89,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
 --------

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,