Restrict in-section merging to Parameters, Methods, Attributes, ...

Author: rsokl

src/custom_inherit/_doc_parse_tools/napoleon_parse_tools.py

@@ -40,13 +40,13 @@ def parse_napoleon_doc(doc, style):
         "Attributes",
         "Methods",
         "Warning",
-        "Notes",
         "Parameters",
         "Other Parameters",
         "Keyword Arguments",
         "Returns",
         "Yields",
         "Raises",
+        "Notes",
         "Warns",
         "See Also",
         "References",
@@ -113,9 +113,10 @@ def merge_section(key, prnt_sec, child_sec, style, merge_within_sections=False):
 
     napoleon_sections_that_cant_merge = [
         "Short Summary",
-        "Example",
         "Examples",
+        "Notes",
     ]
+    napoleon_sections_that_cant_merge.extend([ALIASES[section] for section in napoleon_sections_that_cant_merge if section in ALIASES])
 
     if not prnt_sec and not child_sec:
         return None
@@ -132,14 +133,6 @@ def merge_section(key, prnt_sec, child_sec, style, merge_within_sections=False):
 
     if key in section_items.SECTION_NAMES:
         body = section_items.merge(prnt_sec, child_sec, merge_within_sections, style)
-
-    elif merge_within_sections and key not in napoleon_sections_that_cant_merge:
-        if child_sec is None:
-            body = prnt_sec
-        elif prnt_sec is None:
-            body = child_sec
-        else:
-            body = '\n'.join((prnt_sec, child_sec))
     else:
         body = prnt_sec if child_sec is None else child_sec
 

src/custom_inherit/_doc_parse_tools/numpy_parse_tools.py

@@ -84,13 +84,6 @@ def merge_section(key, prnt_sec, child_sec, merge_within_sections=False):
     Optional[str]
         The output docstring section."""
 
-    doc_sections_that_cant_merge = [
-        "Short Summary",
-        "Deprecation Warning",
-        "Extended Summary",
-        "Examples"
-    ]
-
     if not prnt_sec and not child_sec:
         return None
 
@@ -101,14 +94,6 @@ def merge_section(key, prnt_sec, child_sec, merge_within_sections=False):
 
     if key in section_items.SECTION_NAMES:
         body = section_items.merge(prnt_sec, child_sec, merge_within_sections, "numpy")
-
-    elif merge_within_sections and key not in doc_sections_that_cant_merge:
-        if child_sec is None:
-            body = prnt_sec
-        elif prnt_sec is None:
-            body = child_sec
-        else:
-            body = '\n'.join((prnt_sec, child_sec))
     else:
         body = prnt_sec if child_sec is None else child_sec
 

src/custom_inherit/_doc_parse_tools/section_items.py

@@ -21,7 +21,9 @@ def indent(text, padding):
     "google": " " * 4,
 }
 
-SECTION_NAMES = ("Attributes", "Parameters")
+SECTION_NAMES = {"Attributes", "Parameters", "Methods", "Other Parameters", "Args",
+    "Arguments"
+    "Keyword Args", "Keyword Arguments"}
 
 
 def _render(body, style):

src/custom_inherit/_metaclass_base.py

@@ -15,7 +15,7 @@
 
 
 class DocInheritorBase(type):
-    """ A metaclass that merges the respective docstrings of a parent class and of its child, along with their
+    """A metaclass that merges the respective docstrings of a parent class and of its child, along with their
     properties, methods (including classmethod, staticmethod, decorated methods).
 
     This merge-style must be implemented via the static methods `class_doc_inherit`
@@ -45,9 +45,10 @@ def __new__(mcs, class_name, class_bases, class_dict):
                 (FunctionType, MethodType, classmethod, staticmethod, property),
             )
             if (
-                (attr.startswith("__") and attr.endswith("__") and not mcs.include_special_methods) or
-                not is_doc_type
-            ):
+                attr.startswith("__")
+                and attr.endswith("__")
+                and not mcs.include_special_methods
+            ) or not is_doc_type:
                 continue
 
             is_static_or_class = isinstance(attribute, (staticmethod, classmethod))
@@ -90,7 +91,7 @@ def __new__(mcs, class_name, class_bases, class_dict):
 
     @staticmethod
     def class_doc_inherit(prnt_cls_doc, child_doc):
-        """ Merge the docstrings of a parent class and its child.
+        """Merge the docstrings of a parent class and its child.
 
         Parameters
         ----------
@@ -104,7 +105,7 @@ def class_doc_inherit(prnt_cls_doc, child_doc):
 
     @staticmethod
     def attr_doc_inherit(prnt_attr_doc, child_doc):
-        """ Merge the docstrings of method or property from parent class and the corresponding
+        """Merge the docstrings of method or property from parent class and the corresponding
         attribute of its child.
 
         Parameters

tests/default_styles_test.py

@@ -434,7 +434,7 @@ def child():
         "multi-line\n\nMethods:\n    parent methods\n\nWarning:\n    warnings\n\nParameters:\n    "
         "parent's Parameters\n    alias for Parameters - child's section\n\nOther Parameters:\n    "
         "other\n\nKeyword Arguments:\n    parent's section\n    alias for Keyword Arguments - child's section"
-        "\n\nReturns:\n    return\n\nYields:\n    alias of Yields - parent's\n    yield\n\nRaises:\n    "
+        "\n\nReturns:\n    return\n\nYields:\n    yield\n\nRaises:\n    "
         "raise\n\nNotes:\n    note\n\nWarns:\n    warns\n\nSee Also:\n    see\n\nReferences:\n    "
         "ref\n\nTodo:\n    todo\n\nExamples:\n    child's example"
     )
@@ -629,7 +629,7 @@ def child():
         "\nParameters\n----------\nparent's Parameters\nalias for Parameters - child's section\n"
         "\nOther Parameters\n----------------\nother\n\nKeyword Arguments\n-----------------\n"
         "parent's section\nalias for Keyword Arguments - child's section\n\nReturns\n-------\n"
-        "return\n\nYields\n------\nalias of Yields - parent's\nyield\n\nRaises\n------\nraise\n"
+        "return\n\nYields\n------\nyield\n\nRaises\n------\nraise\n"
         "\nNotes\n-----\nnote\n\nWarns\n-----\nwarns\n\nSee Also\n--------\nsee\n\nReferences\n"
         "----------\nref\n\nTodo\n----\ntodo\n\nExamples\n--------\nchild's example"
     )

tests/inheritance_test.py

@@ -0,0 +1,184 @@
+import pytest
+
+from custom_inherit import DocInheritMeta
+
+
+@pytest.mark.parametrize("style", ["numpy_with_merge", "numpy_napoleon_with_merge"])
+def test_inheritance_numpy_with_merge_styles(style):
+    class Parent(metaclass=DocInheritMeta(style=style)):
+        """Parent.
+
+        Notes
+        -----
+        Blah
+        """
+
+        def meth(self, x, y=None):
+            """
+            Raises
+            ------
+            NotImplementedError"""
+            raise NotImplementedError
+
+    class Child1(Parent):
+        """Child1.
+
+        Methods
+        -------
+        meth: does something
+        """
+
+        def meth(self, x, y=None):
+            """Method description.
+
+            Parameters
+            ----------
+            x: int
+            y: float"""
+            return 0
+
+    class Child2(Parent):
+        """Child 2.
+
+        Methods
+        -------
+        blah : does not much
+        """
+
+        def blah(self):
+            """Method blah2."""
+            pass
+
+    class GrandChild(Child1, Child2):
+        """Grand Child."""
+
+        def meth(self, x, y=None):
+            """
+            Parameters
+            ----------
+            x: int
+            y: float"""
+            return 0
+
+        pass
+
+    """
+    Grand Child.
+    
+    Methods
+    -------
+    blah : does not much
+    meth: does something
+    
+    Notes
+    -----
+    Blah"""
+    assert (
+        GrandChild.__doc__
+        == "Grand Child.\n\nMethods\n-------\nblah : does not much\nmeth: does something\n\nNotes\n-----\nBlah"
+    )
+
+    """
+    Method description.
+    
+    Parameters
+    ----------
+    x: int
+    y: float
+    
+    Raises
+    ------
+    NotImplementedError"""
+    assert (
+        GrandChild.meth.__doc__
+        == "Method description.\n\nParameters\n----------\nx: int\ny: float\n\nRaises\n------\nNotImplementedError"
+    )
+
+
+def test_inheritance_google_with_merge_style():
+    class A(metaclass=DocInheritMeta(style="google_with_merge")):
+        """Testing A.
+
+        Args:
+            a :
+                parameter a.
+            b :
+                parameter b.
+            c :
+                parameter c.
+
+        Returns:
+            None
+
+        Note:
+            Hello
+        """
+
+        pass
+
+    class B(A):
+        """Testing B.
+
+        Parameters:
+            d :
+                parameter d.
+            e :
+                parameter e.
+            f :
+                parameter f.
+
+        Return:
+            None
+        """
+
+        pass
+
+    class C(B):
+        """Testing C.
+
+        Args:
+            g :
+                parameter g.
+            h :
+                parameter h.
+            i :
+                parameter i.
+
+        Note:
+            None
+        """
+
+        pass
+
+    """
+    Testing C.
+
+    Parameters:
+        a :
+            parameter a.
+        b :
+            parameter b.
+        c :
+            parameter c.
+        d :
+            parameter d.
+        e :
+            parameter e.
+        f :
+            parameter f.
+        g :
+            parameter g.
+        h :
+            parameter h.
+        i :
+            parameter i.
+    
+    Returns:
+        None
+    
+    Notes:
+        None"""
+    assert (
+        C.__doc__
+        == "Testing C.\n\nParameters:\n    a :\n        parameter a.\n    b :\n        parameter b.\n    c :\n        parameter c.\n    d :\n        parameter d.\n    e :\n        parameter e.\n    f :\n        parameter f.\n    g :\n        parameter g.\n    h :\n        parameter h.\n    i :\n        parameter i.\n\nReturns:\n    None\n\nNotes:\n    None"
+    )