search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.55k stars 2.12k forks source link

Add option include-subclasses to inheritance-diagram #8191

Open doerwalter opened 4 years ago

doerwalter commented 4 years ago

Is your feature request related to a problem? Please describe.

When I have a module that contains many classes and some of them are related through inheritance and some are not, then I have the following problem: I'd like to create an inheritance diagram for one of the classes in this module and all of its subclasses. However when I specify the module in inheritance-diagram the diagram will contain the unrelated classes too. top-classes doesn't work either. The only working approach is to list each of the subclasses individually.

Describe the solution you'd like I'd like an option to specify that any subclass of classes in the list of classes for the inheritance-diagram should be included in the diagram too.

I.e. if I have a module m with the following classes:

class A: ...
class B: ...
class C(B): ...
class D(B): ...

Then the following Sphinx code:

.. inheritance-diagram:: m.B
    :include-subclasses:

will create an inheritance diagram including the classes B, C and D.

Additional context

I have this problem in the following project:

http://python.livinglogic.de/XIST_Howto.html

The class Node has 25 subclasses, so to show Node and all of its subclasses the Sphinx code looks like this:

.. inheritance-diagram:: ll.xist.xsc.Node ll.xist.xsc.Frag ll.xist.xsc.Element ll.xist.xsc.Attrs ll.xist.xsc.Entity ll.xist.xsc.Attr ll.xist.xsc.BoolAttr ll.xist.xsc.ColorAttr ll.xist.xsc.NumberAttr ll.xist.xsc.FloatAttr ll.xist.xsc.IntAttr ll.xist.xsc.IDAttr ll.xist.xsc.StyleAttr ll.xist.xsc.TextAttr ll.xist.xsc.URLAttr ll.xist.xsc.CharacterData ll.xist.xsc.Text ll.xist.xsc.CharRef ll.xist.xsc.amp ll.xist.xsc.apos ll.xist.xsc.gt ll.xist.xsc.lt ll.xist.xsc.quot ll.xist.xsc.Comment ll.xist.xsc.DocType ll.xist.xsc.ProcInst
    :parts: 1

With this its likely that I might miss a class when typing this list, or might forget to add it when a new subclass gets added. With the include-subclasses option the code would look like this:

.. inheritance-diagram:: ll.xist.xsc.Node
    :include-subclasses:
    :parts: 1

which IMHO is much simpler and saver.

Pull request

A pull request that implements this feature can be found here:

https://github.com/sphinx-doc/sphinx/pull/8159

doerwalter commented 3 years ago

Is there something missing that I still need to provide? What can I do to move this pull request along?

polfeliu commented 3 years ago

This feature would be great, I would like to use it for a project of mine. Is there anything we can do to get this moving? Seems to be stuck for no reason.

aantn commented 2 years ago

I'm also interested in this.