feat: Add merge option to merge docstrings downwards

Issue-2: #2
PR-3: #3
Co-authored-by: Timothée Mazzucotelli <dev@pawamoy.fr>

Author: thomasmarwitz

README.md

@@ -37,3 +37,52 @@ plugins:
 
 The extension will iterate on every class and their members
 to set docstrings from parent classes when they are not already defined.
+
+The extension accepts a `merge` option, that when set to true
+will actually merge all parent docstrings in the class hierarchy
+to the child docstring, if any.
+
+```yaml
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          extensions:
+          - griffe_inherited_docstrings:
+              merge: true
+```
+
+```python
+class A:
+    def method(self):
+        """Method in A."""
+
+class B(A):
+    def method(self):
+        ...
+
+class C(B):
+    ...
+
+class D(C):
+    def method(self):
+        """Method in D."""
+
+class E(D):
+    def method(self):
+        """Method in E."""
+```
+
+With the code above, docstrings will be merged like following:
+
+Class | Method docstring
+----- | ----------------
+`A`   | Method in A.
+`B`   | Method in A.
+`C`   | Method in A.
+`D`   | Method in A.<br><br>Method in D.
+`E`   | Method in A.<br><br>Method in D.<br><br>Method in E.
+
+WARNING: **Limitation**
+This extension runs once on whole packages. There is no way to toggle merging or simple inheritance for specifc objects.

src/griffe_inherited_docstrings/extension.py

@@ -5,40 +5,74 @@
 import contextlib
 from typing import TYPE_CHECKING, Any
 
-from griffe import AliasResolutionError, Extension
+from griffe import AliasResolutionError, Docstring, Extension
 
 if TYPE_CHECKING:
-    from griffe import Docstring, Module, Object
+    from griffe import Module, Object
 
 
-def _inherited_docstring(obj: Object) -> Docstring | None:
-    for parent_class in obj.parent.mro():  # type: ignore[union-attr]
-        try:
-            if docstring := parent_class.members[obj.name].docstring:
-                return docstring
-        except KeyError:
-            pass
+def _docstring_above(obj: Object) -> Docstring | None:
+    with contextlib.suppress(IndexError, KeyError):
+        parent = obj.parent.mro()[0]  # type: ignore[union-attr]
+        return parent.members[obj.name].docstring
     return None
 
 
-def _inherit_docstrings(obj: Object) -> None:
+def _inherit_docstrings(obj: Object, *, merge: bool = False, seen: set[str] | None = None) -> None:
+    if seen is None:
+        seen = set()
+
+    if obj.path in seen:
+        return
+
+    seen.add(obj.path)
+
     if obj.is_module:
         for member in obj.members.values():
             if not member.is_alias:
                 with contextlib.suppress(AliasResolutionError):
-                    _inherit_docstrings(member)  # type: ignore[arg-type]
+                    _inherit_docstrings(member, merge=merge, seen=seen)  # type: ignore[arg-type]
+
     elif obj.is_class:
+        # Recursively handle top-most parents first.
+        # It means that we can just check the first parent
+        # when actually inheriting (and optionally merging) a docstring,
+        # since the docstrings of the other parents have already been inherited.
+        for parent in reversed(obj.mro()):  # type: ignore[attr-defined]
+            _inherit_docstrings(parent, merge=merge, seen=seen)
+
         for member in obj.members.values():
             if not member.is_alias:
-                if member.docstring is None and (inherited := _inherited_docstring(member)):  # type: ignore[arg-type]
-                    member.docstring = inherited
+                if docstring_above := _docstring_above(member):  # type: ignore[arg-type]
+                    if merge:
+                        if member.docstring is None:
+                            member.docstring = Docstring(
+                                docstring_above.value,
+                                parent=member,  # type: ignore[arg-type]
+                                parser=docstring_above.parser,
+                                parser_options=docstring_above.parser_options,
+                            )
+                        elif member.docstring.value:
+                            member.docstring.value = docstring_above.value + "\n\n" + member.docstring.value
+                        else:
+                            member.docstring.value = docstring_above.value
+                    elif member.docstring is None:
+                        member.docstring = docstring_above
                 if member.is_class:
-                    _inherit_docstrings(member)  # type: ignore[arg-type]
+                    _inherit_docstrings(member, merge=merge, seen=seen)  # type: ignore[arg-type]
 
 
 class InheritDocstringsExtension(Extension):
     """Griffe extension for inheriting docstrings."""
 
+    def __init__(self, *, merge: bool = False) -> None:
+        """Initialize the extension by setting the merge flag.
+
+        Parameters:
+            merge: Whether to merge the docstrings from the parent classes into the docstring of the member.
+        """
+        self.merge = merge
+
     def on_package_loaded(self, *, pkg: Module, **kwargs: Any) -> None:  # noqa: ARG002
         """Inherit docstrings from parent classes once the whole package is loaded."""
-        _inherit_docstrings(pkg)
+        _inherit_docstrings(pkg, merge=self.merge, seen=set())

tests/test_extension.py

@@ -16,7 +16,6 @@ def test_inherit_docstrings() -> None:
                 class Parent:
                     def method(self):
                         '''Docstring from parent method.'''
-
                 class Child(Parent):
                     def method(self):
                         ...
@@ -25,3 +24,66 @@ def method(self):
         extensions=Extensions(InheritDocstringsExtension()),
     ) as package:
         assert package["Child.method"].docstring.value == package["Parent.method"].docstring.value
+
+
+def test_inherit_and_merge_docstrings() -> None:
+    """Inherit and merge docstrings from parent classes."""
+    attr_doc = "Attribute docstring from class"
+    meth_doc = "Method docstring from class"
+    code = f"""
+    # Base docstrings.
+    class A:
+        attr = 42
+        '''{attr_doc} A.'''
+
+        def meth(self):
+            '''{meth_doc} A.'''
+
+
+    # Redeclare members but without docstrings.
+    class B(A):
+        attr = 42
+
+        def meth(self):
+            ...
+
+
+    # Redeclare members but with empty docstrings.
+    class C(B):
+        attr = 42
+        ''''''
+
+        def meth(self):
+            ''''''
+
+
+    # Redeclare members with docstrings.
+    class D(C):
+        attr = 42
+        '''{attr_doc} D.'''
+
+        def meth(self):
+            '''{meth_doc} D.'''
+
+
+    # Redeclare members with docstrings again.
+    class E(D):
+        attr = 42
+        '''{attr_doc} E.'''
+
+        def meth(self):
+            '''{meth_doc} E.'''
+    """
+    with temporary_visited_package(
+        "package",
+        modules={"__init__.py": code},
+        extensions=Extensions(InheritDocstringsExtension(merge=True)),
+    ) as package:
+        assert package["B.attr"].docstring.value == package["A.attr"].docstring.value
+        assert package["B.meth"].docstring.value == package["A.meth"].docstring.value
+        assert package["C.attr"].docstring.value == package["A.attr"].docstring.value
+        assert package["C.meth"].docstring.value == package["A.meth"].docstring.value
+        assert package["D.attr"].docstring.value == package["A.attr"].docstring.value + "\n\n" + f"{attr_doc} D."
+        assert package["D.meth"].docstring.value == package["A.meth"].docstring.value + "\n\n" + f"{meth_doc} D."
+        assert package["E.attr"].docstring.value == package["D.attr"].docstring.value + "\n\n" + f"{attr_doc} E."
+        assert package["E.meth"].docstring.value == package["D.meth"].docstring.value + "\n\n" + f"{meth_doc} E."