Autodoc does not find inherited docstring of __init__ method

[timhoffm]

Describe the bug

Found in https://github.com/matplotlib/matplotlib/issues/22831#issuecomment-3019698791

I have not been able to fully separate the issue yet. It has to be an edge case as it works for simple a very simple inherited case. For now, the reproducer still needs the original matplotlib class. What I have found out is that sphinx.util.inspect.getdoc() does not find the __init__ docstring, whereas stdlibs inpsect.getdoc() does.

Why has sphinx its own getdoc() function and how does it differ from the standard lib?

---

Notes on the "speciality" of the case:

The full class diagram can be seen at https://matplotlib.org/stable/api/animation_api.html#writer-classes, simplified

The problematic class is FFmpegFileWriter

AbstractMovieWriter(ABC)
        |
        v
MovieWriter
  # __init__ with docstring
  # docstring rendered
        |
        v
FileMovieWriter
  # __init__ without docstring
  # docstring rendered
        |
        v
FFmpegFileWriter   <-----------------  FFMpegBase
  # __init__ without docstring           # no __init__
  # *no* docstring rendered

• we have multiple inheritance, one of which (FFMpegBase) is a mixin without __init__
• AbstractMovieWriter is an ABC and due to the involved metaclass mechanism

  >>> '__init__' in FFMpegFileWriter.__class__.__dict__
  False
  

• The docstring in question to inherit comes from MovieWriter, i.e. two parents up. The in-between class FileMovieWriter has an __init__ without an own docstring. It's doc correctly show the inherited docstring of MovieWriter.

How to Reproduce

import inspect
import sphinx.util.inspect as sinspect

inspect.getdoc(FFMpegFileWriter.__init__)  # works
sinspect.getdoc(FFMpegFileWriter.__init__)  # does not work

Environment Information

sphinx 8.2.3

Sphinx extensions

sphinx.ext.autodoc

Additional context

No response

[timhoffm]

Remark: That inheriting the __init__ docstring does not work is related to multiple inheritance FFMpegFileWriter(FFMpegBase, FileMovieWriter). The following changes all result in the MovieWriter.__init__ being shown for FFMpegFileWriter:

• removing inheritance from FFMpegBase: FFMpegFileWriter(FileMovieWriter)
• flipping the inheritance order to FFMpegFileWriter(FileMovieWriter, FFMpegBase)
• going one level up from FileMovieWriter to MovieWriter: FFMpegFileWriter(FFMpegBase, MovieWriter)