Merge pull request #41 from rsokl/fix-merging-with-inherit

Fix merging with inherit

Author: rsokl

README.md

@@ -170,26 +170,25 @@ Utilize a built-in style by specifying any of the following names (as a string),
         from the parent and child are merged gracefully with nice formatting. The child's docstring sections take precedence
 	in the case of overlap.
 
-- `"numpy_with_merge"`: Behaves identically to the "numpy" style, but also merges sections that overlap,
-    instead of only keeping the child's section. All sections are concerned except sections "Short Summary",
-    "Extended Summary", "Deprecation Warning" and "Examples" for which the "numpy" style behaviour applies.
+- `"numpy_with_merge"`: Behaves identically to the "numpy" style, but also merges - with de-duplication - sections that overlap,
+    instead of only keeping the child's section. The sections that are merged are "Attributes", "Parameters",
+    "Methods", "Other Parameters", and "Keyword Arguments".
 
 - `"google"`: Google-styled docstrings from the parent and child are merged gracefully
 	with nice formatting. The child's docstring sections take precedence in the case of overlap.
 	This adheres to the [napoleon specification for the Google style](http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html#example-google-style-python-docstrings).
 
-- `"google_with_merge"`: Behaves identically to the "google" style, but also merges sections that overlap,
-    instead of only keeping the child's section. All sections are concerned except sections "Short Summary",
-    "Example" and "Examples" (or coresponding aliases) for which the 'google' style applies.
+- `"google_with_merge"`: Behaves identically to the "google" style, but also merges - with de-duplication - sections that overlap,
+    instead of only keeping the child's section. The sections that are merged are "Attributes", "Parameters",
+    "Methods", "Other Parameters", and "Keyword Arguments" (or their [aliases](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/index.html#docstring-sections)).
 
 - `"numpy_napoleon"`: NumPy-styled docstrings from the parent and child are merged gracefully
 	with nice formatting. The child's docstring sections take precedence in the case of overlap.
 	This adheres to the [napoleon specification for the NumPy style](http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html#example-numpy).
 
-- `"numpy_napoleon_with_merge"`: Behaves identically to the 'numpy_napoleon' style, but also merges sections
-    that overlap, instead of only keeping the child's section. All sections are concerned except sections
-    "Short Summary", "Example" and "Examples" (or coresponding aliases) for which the 'numpy_napoleon' style
-    behaviour applies.
+- `"numpy_napoleon_with_merge"`: Behaves identically to the 'numpy_napoleon' style, but also merges - with de-duplication - sections
+    that overlap, instead of only keeping the child's section. The sections that are merged are "Attributes", "Parameters",
+    "Methods", "Other Parameters", and "Keyword Arguments" (or their [aliases](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/index.html#docstring-sections)).
 
 - `"reST"`: reST-styled docstrings from the parent and child are merged gracefully
 	with nice formatting. Docstring sections are specified by
@@ -198,7 +197,7 @@ Utilize a built-in style by specifying any of the following names (as a string),
 
 For the `numpy`, `numpy_with_merge`, `numpy_napoleon`, `numpy_napoleon_with_merge`, `google` and `google_with_merge` styles, if the parent's docstring contains a "Raises" section and the child's docstring implements a "Returns" or a "Yields" section instead, then the "Raises" section is not included in the resulting docstring. This is to accomodate for the relatively common use case in which an abstract method/property raises `NotImplementedError`. Child classes that implement this method/property clearly will not raise this. Of course, any "Raises" section that is explicitly included in the child's docstring will appear in the resulting docstring.
 
-Detailed documentation and example cases for the default styles can be found [here](https://github.com/meowklaski/custom_inherit/blob/master/custom_inherit/_style_store.py)
+Detailed documentation and example cases for the default styles can be found [here](https://github.com/rsokl/custom_inherit/blob/master/src/custom_inherit/_style_store.py)
 
 ## Making New Inheritance Styles
 Implementing your inheritance style is simple.

src/custom_inherit/_doc_parse_tools/napoleon_parse_tools.py

@@ -7,6 +7,17 @@
 
 __all__ = ["merge_google_napoleon_docs", "merge_numpy_napoleon_docs"]
 
+ALIASES = {
+    "Args": "Parameters",
+    "Arguments": "Parameters",
+    "Keyword Args": "Keyword Arguments",
+    "Return": "Returns",
+    "Warnings": "Warning",
+    "Yield": "Yields",
+    "Note": "Notes",
+    "Example": "Examples",
+}
+
 
 def parse_napoleon_doc(doc, style):
     """ Extract the text from the various sections of a numpy-formatted docstring.
@@ -29,30 +40,20 @@ def parse_napoleon_doc(doc, style):
         "Attributes",
         "Methods",
         "Warning",
-        "Note",
         "Parameters",
         "Other Parameters",
         "Keyword Arguments",
         "Returns",
         "Yields",
         "Raises",
+        "Notes",
         "Warns",
         "See Also",
         "References",
         "Todo",
-        "Example",
         "Examples",
     ]
 
-    aliases = {
-        "Args": "Parameters",
-        "Arguments": "Parameters",
-        "Keyword Args": "Keyword Arguments",
-        "Return": "Returns",
-        "Warnings": "Warning",
-        "Yield": "Yields",
-    }
-
     doc_sections = OrderedDict([(key, None) for key in napoleon_sections])
 
     section_items.set_defaults(doc_sections)
@@ -75,8 +76,8 @@ def parse_napoleon_doc(doc, style):
                 if style == "numpy"
                 else (line[:-1] if line.endswith(":") else line)
             )
-            if header and (header in doc_sections or header in aliases):
-                doc_sections[aliases.get(key, key)] = (
+            if header and (header in doc_sections or header in ALIASES):
+                doc_sections[ALIASES.get(key, key)] = (
                     "\n".join(body).rstrip() if body else None
                 )
                 body = []
@@ -86,7 +87,7 @@ def parse_napoleon_doc(doc, style):
             else:
                 body.append(line)
         except StopIteration:
-            doc_sections[aliases.get(key, key)] = "\n".join(body)
+            doc_sections[ALIASES.get(key, key)] = "\n".join(body)
             break
 
     section_items.parse(doc_sections)
@@ -110,12 +111,6 @@ def merge_section(key, prnt_sec, child_sec, style, merge_within_sections=False):
     Optional[str]
         The output docstring section."""
 
-    napoleon_sections_that_cant_merge = [
-        "Short Summary",
-        "Example",
-        "Examples",
-    ]
-
     if not prnt_sec and not child_sec:
         return None
 
@@ -131,14 +126,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

@@ -9,19 +9,26 @@
 except ImportError:
     # for Python < 3.3
     def indent(text, padding):
-        return ''.join(padding+line for line in text.splitlines(True))
+        return "".join(padding + line for line in text.splitlines(True))
 
 
-_RE_PATTERN_ITEMS = re.compile(
-    r"(\**\w+)(.*?)(?:$|(?=\n\**\w+))", flags=re.DOTALL
-)
+_RE_PATTERN_ITEMS = re.compile(r"(\**\w+)(.*?)(?:$|(?=\n\**\w+))", flags=re.DOTALL)
 
 _STYLE_TO_PADDING = {
     "numpy": "",
     "google": " " * 4,
 }
 
-SECTION_NAMES = ("Attributes", "Parameters")
+SECTION_NAMES = {
+    "Attributes",
+    "Parameters",
+    "Methods",
+    "Other Parameters",
+    "Args",
+    "Arguments",
+    "Keyword Args",
+    "Keyword Arguments",
+}
 
 
 def _render(body, style):
@@ -66,7 +73,9 @@ def parse(doc_sections):
     for section_name in SECTION_NAMES:
         section_content = doc_sections[section_name]
         if section_content:
-            doc_sections[section_name] = OrderedDict(_RE_PATTERN_ITEMS.findall(inspect.cleandoc(section_content)))
+            doc_sections[section_name] = OrderedDict(
+                _RE_PATTERN_ITEMS.findall(inspect.cleandoc(section_content))
+            )
 
 
 def merge(prnt_sec, child_sec, merge_within_sections, 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

src/custom_inherit/_style_store.py

@@ -444,9 +444,9 @@ def numpy_with_merge(prnt_doc, child_doc):
                 Parameters
                 ----------
                 x: int
-                    description of x
+                    parent's description of x
                 y: Union[None, int]
-                    description of y
+                    parent's description of y
 
                 Raises
                 ------
@@ -463,8 +463,10 @@ def numpy_with_merge(prnt_doc, child_doc):
 
                 Parameters
                 ----------
+                y: int
+                    childs's description of y
                 z: Union[None, int]
-                    description of z
+                    child's description of z
 
                 Returns
                 -------
@@ -486,11 +488,11 @@ def numpy_with_merge(prnt_doc, child_doc):
                 Parameters
                 ----------
                 x: int
-                    description of x
-                y: Union[None, int]
-                    description of y
+                    parent's description of x
+                y: int
+                    childs's description of y
                 z: Union[None, int]
-                    description of z
+                    child's description of z
 
                 Returns
                 -------

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"
     )