From 1f136215c18fc75eb9402ec7da083f9022703d71 Mon Sep 17 00:00:00 2001 From: Michael Goerz Date: Sun, 10 Mar 2019 18:37:05 -0400 Subject: [PATCH 1/2] 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 | 1 + doc/conf.py | 2 +- doc/usage/extensions/inheritance.rst | 51 +++++++++++++++++++++++++--- sphinx/ext/inheritance_diagram.py | 16 ++++++--- 4 files changed, 59 insertions(+), 11 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.) + 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 ------------- 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. + *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, From 19a23142585f5fa5351f677acf2e70d036f52cdf Mon Sep 17 00:00:00 2001 From: Michael Goerz Date: Mon, 11 Mar 2019 14:35:50 -0400 Subject: [PATCH 2/2] Install graphiz on Travis This is required to generate inheritance diagrams (as there is now an example inheritance diagram in the documentation of the extension generating such diagrams) --- .travis.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.travis.yml b/.travis.yml index 5a49bf106..7bc822d70 100644 --- a/.travis.yml +++ b/.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