new defaults styles with inner section merging

Author: Benoit Fuentes

README.md

@@ -155,22 +155,35 @@ Utilize a built-in style by specifying any of the following names (as a string),
 
 - `"numpy"`: [NumPy-styled docstrings](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#docstring-standard) 
         from the parent and child are merged gracefully with nice formatting. The child's docstring sections take precedence 
-	in the case of overlap. 
+	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.
 
 - `"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.
+
 - `"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.
+
 - `"reST"`: reST-styled docstrings from the parent and child are merged gracefully
 	with nice formatting. Docstring sections are specified by 
 	[reST section titles](http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections).
 	The child's docstring sections take precedence in the case of overlap.
 
-For the `numpy`, `numpy_napoleon`, and `google` 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.
+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)
 

src/custom_inherit/__init__.py

@@ -4,7 +4,11 @@
 
 from ._decorator_base import DocInheritDecorator as _DocInheritDecorator
 from ._metaclass_base import DocInheritorBase as _DocInheritorBase
-from ._style_store import google, numpy, numpy_napoleon, parent, reST
+from . import _style_store
+from ._style_store import (
+    google, numpy, numpy_napoleon, parent, reST,
+    google_with_merge, numpy_napoleon_with_merge, numpy_with_merge
+)
 from ._version import get_versions
 
 __version__ = get_versions()["version"]
@@ -113,7 +117,6 @@ def items(self):
         """ D.items() -> a set-like object providing a view on D's items"""
         return self._store.items()
 
-
 store = _Store([(key, getattr(_style_store, key)) for key in _style_store.__all__])
 
 

src/custom_inherit/_doc_parse_tools/napoleon_parse_tools.py

@@ -87,7 +87,7 @@ def parse_napoleon_doc(doc, style):
     return doc_sections
 
 
-def merge_section(key, prnt_sec, child_sec, style):
+def merge_section(key, prnt_sec, child_sec, style, merge_within_sections=False):
     """ Synthesize a output napoleon docstring section.
 
     Parameters
@@ -102,6 +102,13 @@ def merge_section(key, prnt_sec, child_sec, style):
     -------
     Optional[str]
         The output docstring section."""
+
+    napoleon_sections_that_cant_merge = [
+        "Short Summary",
+        "Example",
+        "Examples",
+    ]
+
     if prnt_sec is None and child_sec is None:
         return None
 
@@ -114,13 +121,20 @@ def merge_section(key, prnt_sec, child_sec, style):
             header = "\n".join((key, "".join("-" for i in range(len(key))), ""))
         else:
             header = "\n".join((key + ":", ""))
-
-    body = prnt_sec if child_sec is None else child_sec
+    if 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
 
     return header + body
 
 
-def merge_all_sections(prnt_sctns, child_sctns, style):
+def merge_all_sections(prnt_sctns, child_sctns, style, merge_within_sections=False):
     """ Merge the doc-sections of the parent's and child's attribute into a single docstring.
 
     Parameters
@@ -141,13 +155,19 @@ def merge_all_sections(prnt_sctns, child_sctns, style):
         prnt_sctns["Raises"] = None
 
     for key in prnt_sctns:
-        sect = merge_section(key, prnt_sctns[key], child_sctns[key], style)
+        sect = merge_section(
+            key,
+            prnt_sctns[key],
+            child_sctns[key],
+            style,
+            merge_within_sections=merge_within_sections
+        )
         if sect is not None:
             doc.append(sect)
     return "\n\n".join(doc) if doc else None
 
 
-def merge_numpy_napoleon_docs(prnt_doc=None, child_doc=None):
+def merge_numpy_napoleon_docs(prnt_doc=None, child_doc=None, merge_within_sections=False):
     """ Merge two numpy-style docstrings into a single docstring, according to napoleon docstring sections.
 
     Given the numpy-style docstrings from a parent and child's attributes, merge the docstring
@@ -172,11 +192,14 @@ def merge_numpy_napoleon_docs(prnt_doc=None, child_doc=None):
         The merged docstring. """
     style = "numpy"
     return merge_all_sections(
-        parse_napoleon_doc(prnt_doc, style), parse_napoleon_doc(child_doc, style), style
+        parse_napoleon_doc(prnt_doc, style),
+        parse_napoleon_doc(child_doc, style),
+        style,
+        merge_within_sections=merge_within_sections
     )
 
 
-def merge_google_napoleon_docs(prnt_doc=None, child_doc=None):
+def merge_google_napoleon_docs(prnt_doc=None, child_doc=None, merge_within_sections=False):
     """ Merge two google-style docstrings into a single docstring, according to napoleon docstring sections.
 
         Given the google-style docstrings from a parent and child's attributes, merge the docstring
@@ -201,5 +224,8 @@ def merge_google_napoleon_docs(prnt_doc=None, child_doc=None):
         The merged docstring. """
     style = "google"
     return merge_all_sections(
-        parse_napoleon_doc(prnt_doc, style), parse_napoleon_doc(child_doc, style), style
+        parse_napoleon_doc(prnt_doc, style),
+        parse_napoleon_doc(child_doc, style),
+        style,
+        merge_within_sections=merge_within_sections
     )

src/custom_inherit/_doc_parse_tools/numpy_parse_tools.py

@@ -61,7 +61,7 @@ def parse_numpy_doc(doc):
     return doc_sections
 
 
-def merge_section(key, prnt_sec, child_sec):
+def merge_section(key, prnt_sec, child_sec, merge_within_sections=False):
     """ Synthesize a output numpy docstring section.
 
     Parameters
@@ -76,6 +76,14 @@ def merge_section(key, prnt_sec, child_sec):
     -------
     Optional[str]
         The output docstring section."""
+
+    doc_sections_that_cant_merge = [
+        "Short Summary",
+        "Deprecation Warning",
+        "Extended Summary",
+        "Examples"
+    ]
+
     if prnt_sec is None and child_sec is None:
         return None
 
@@ -84,15 +92,20 @@ def merge_section(key, prnt_sec, child_sec):
     else:
         header = "\n".join((key, "".join("-" for i in range(len(key))), ""))
 
-    if child_sec is None:
-        body = prnt_sec
+    if 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 = child_sec
+        body = prnt_sec if child_sec is None else child_sec
 
     return header + body
 
 
-def merge_all_sections(prnt_sctns, child_sctns):
+def merge_all_sections(prnt_sctns, child_sctns, merge_within_sections=False):
     """ Merge the doc-sections of the parent's and child's attribute into a single docstring.
 
     Parameters
@@ -113,13 +126,18 @@ def merge_all_sections(prnt_sctns, child_sctns):
         prnt_sctns["Raises"] = None
 
     for key in prnt_sctns:
-        sect = merge_section(key, prnt_sctns[key], child_sctns[key])
+        sect = merge_section(
+            key,
+            prnt_sctns[key],
+            child_sctns[key],
+            merge_within_sections=merge_within_sections
+        )
         if sect is not None:
             doc.append(sect)
     return "\n\n".join(doc) if doc else None
 
 
-def merge_numpy_docs(prnt_doc=None, child_doc=None):
+def merge_numpy_docs(prnt_doc=None, child_doc=None, merge_within_sections=False):
     """ Merge two numpy-style docstrings into a single docstring.
 
     Given the numpy-style docstrings from a parent and child's attributes, merge the docstring
@@ -141,4 +159,8 @@ def merge_numpy_docs(prnt_doc=None, child_doc=None):
     Union[str, None]
         The merged docstring.
         """
-    return merge_all_sections(parse_numpy_doc(prnt_doc), parse_numpy_doc(child_doc))
+    return merge_all_sections(
+        parse_numpy_doc(prnt_doc),
+        parse_numpy_doc(child_doc),
+        merge_within_sections=merge_within_sections
+    )