feature: Add option s.t. overridden members are able to "inherit" docstrings from corresponding members in parent classes

[thomasmarwitz]

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

This problem occurred during the migration from sphinx to mkdocs, specifically when auto-generating the API documentation ¹.

In sphinx, it is possible (apparently the default when turning autodoc_default_options = { "inherited-members": True, ... } on) to have a docstring of a method in a parent class appear in the documentation of a subclass that overrides this method without supplying a new docstring.

Example²:

class Shape:
    contour: list[Point]
    def surface_area(self):
        """Return the surface area in square meters."""
        return numerical_integration(self.contour)
        
class Rectange(Shape)
    def surface_area(self):
        return distance(self.cotour[2], self.contour[0]) * distance(self.contour[3], self.contour[1])

We would like to have "Return the surface area in square meters." also appear for surface_area.

Additionally, sphinx performs some merging of docstrings³, as demonstrated below.
Example:

class Shape:
    contour: list[Point]
    def surface_area(self):
        """Return the surface area in square meters."""
        return numerical_integration(self.contour)
        
class Rectange(Shape)
    def surface_area(self):
		"""Note: This is way faster than the calculation for general shapes!"""
        return distance(self.cotour[2], self.contour[0]) * distance(self.contour[3], self.contour[1])

For this example, the documentation for surface_area should include: "Return the surface area in square meters. Note: This is way faster than the calculation for general shapes!"

Describe the solution you'd like

I'd like a configurable setting e.g. docstring_inherit_strategy that can be changed to realize a "plain insertion" of parent docstrings for members or to "merge" docstrings from the inheritance tree.

I'm already working on a solution as I saw that contributions are always welcome 😃

Describe alternatives you've considered

• Continue using sphinx >.>.
• Setting inherited_members: true in mkdocs.yml, but this doesn't achieve the described behavior⁴.

Additional context

Footnotes

1. https://github.com/Quantco/metalearners/pull/81 ↩

2. https://github.com/Quantco/metalearners/pull/81#issuecomment-2317285231 ↩

3. Compare MetaLearner.evaluate with e.g. RLearner.evaluate. Just before Parameters, RLearner has an additional paragraph that stems from this docstring ↩

4. https://github.com/Quantco/metalearners/pull/81#issuecomment-2317267997 ↩

[thomasmarwitz]

Closing as this effort is now continued here: mkdocstrings/griffe-inherited-docstrings#2