Merge pull request #31 from Boubsi/inner_section_merging

Inner section merging and special method option

Author: rsokl

README.md

@@ -53,10 +53,10 @@ class Parent(metaclass=DocInheritMeta(style="numpy")):
            ----------
            x: int
               blah-x
-              
+
            y: Optional[int]
               blah-y
-           
+
            Raises
            ------
            NotImplementedError"""
@@ -85,7 +85,7 @@ Because we specified `style="numpy"` in `DocInheritMeta`, the inherited docstrin
       ----------
       x: int
          blah-x
-         
+
       y: Optional[int]
          blah-y
 
@@ -146,44 +146,69 @@ class Parent(metaclass=DocInheritMeta(style="numpy", abstract_base_class=True)):
 
 For the "numpy", "google", and "napoleon_numpy" inheritance styles, one then only needs to specify the "Returns" or "Yields" section in the derived class' attribute docstring for it to have a fully-detailed docstring.
 
+Another option is to be able to decide whether to include all special methods, meaning methods that start and
+end by "__" such as "__init__" method, or not in the doctstring inheritance process. Such an option can be pass
+to the `DocInheritMeta` metaclass constructor:
+
+```python
+# Each child class will also merge the special methods' docstring of its parent class
+class Parent(metaclass=DocInheritMeta(style="numpy", include_special_methods=True)):
+   ...
+```
+
+Special methods are not included by default.
+
 ## Built-in Styles
 
 Utilize a built-in style by specifying any of the following names (as a string), wherever the `style` parameter is to be specified. The built-in styles are:
 
 - `"parent"`: Wherever the docstring for a child-class' attribute (or for the class itself) is
 	`None`, inherit the corresponding docstring from the parent. (Deprecated in Python 3.5)
 
-- `"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. 
+- `"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.
+
+- `"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 
+	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)
 
 ## Making New Inheritance Styles
-Implementing your inheritance style is simple. 
+Implementing your inheritance style is simple.
 
 - Provide an inheritance style on the fly wherever a style parameter is specified:
     - Supply any function of the form: `func(prnt_doc: str, child_doc: str) -> str`
 
 - Log an inheritance style, and refer to it by name wherever a style parameter is specified, using either:
-    - `custom_inherit.store["my_style"] = func` 
-    - `custom_inherit.add_style("my_style", func)`. 
-    
+    - `custom_inherit.store["my_style"] = func`
+    - `custom_inherit.add_style("my_style", func)`.
+
 ## Installation and Getting Started
 Install via pip:
 
@@ -193,7 +218,7 @@ Install via pip:
 Install via conda:
 
 ```
-    conda install -c conda-forge custom-inherit 
+    conda install -c conda-forge custom-inherit
 ```
 
 or
@@ -251,7 +276,7 @@ custom_inherit.doc_inherit(parent, style="parent"):
         Parameters
         ----------
         parent : Union[str, Any]
-            The object whose docstring, is utilized as the parent docstring 
+            The object whose docstring, is utilized as the parent docstring
 	    during the docstring merge. Or, a string can be provided directly.
 
         style : Union[Hashable, Callable[[str, str], str]], optional (default: "parent")

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__])
 
 
@@ -140,7 +143,7 @@ def remove_style(style):
         store.pop(style)
 
 
-def DocInheritMeta(style="parent", abstract_base_class=False):
+def DocInheritMeta(style="parent", abstract_base_class=False, include_special_methods=False):
     """ 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).
 
@@ -156,13 +159,18 @@ def DocInheritMeta(style="parent", abstract_base_class=False):
         will be an abstract base class, whose derived classes will inherit docstrings
         using the numpy-style inheritance scheme.
 
+    include_special_methods: bool, optional (defaul: False)
+        Wether special methods of class (i.e. starting en ending with "__") are included in the docstring
+        inheritance process.
+
 
     Returns
     -------
     custom_inherit.DocInheritorBase"""
 
     merge_func = store[style]
     metaclass = _DocInheritorBase
+    metaclass.include_special_methods = include_special_methods
     metaclass.class_doc_inherit = staticmethod(merge_func)
     metaclass.attr_doc_inherit = staticmethod(merge_func)
 

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

src/custom_inherit/_metaclass_base.py

@@ -21,6 +21,8 @@ class DocInheritorBase(type):
     This merge-style must be implemented via the static methods `class_doc_inherit`
     and `attr_doc_inherit`, which are set within `custom_inherit.DocInheritMeta`."""
 
+    include_special_methods = False
+
     def __new__(mcs, class_name, class_bases, class_dict):
         # inherit class docstring: the docstring is constructed by traversing
         # the mro for the class and merging their docstrings, with each next
@@ -42,8 +44,10 @@ def __new__(mcs, class_name, class_bases, class_dict):
                 attribute,
                 (FunctionType, MethodType, classmethod, staticmethod, property),
             )
-
-            if (attr.startswith("__") and attr.endswith("__")) or not is_doc_type:
+            if (
+                (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))