Merge pull request #6164 from goerz/inheritance_diagram

Fix docs of inheritance-diagram "parts" option

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