IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Fix docs of inheritance-diagram "parts" option

Browse Source 
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
This commit is contained in:
Michael Goerz
2019-03-10 18:37:05 -04:00
parent 332dd5d89f
commit 1f136215c1
4 changed files with 59 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
doc/usage/extensions/inheritance.rst
View File

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