include_special_method option in DocInheritMeta

Author: Benoit Fuentes

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,15 +146,27 @@ 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 
+- `"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,
@@ -179,7 +191,7 @@ Utilize a built-in style by specifying any of the following names (as a string),
     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.
 
@@ -188,15 +200,15 @@ For the `numpy`, `numpy_with_merge`, `numpy_napoleon`, `numpy_napoleon_with_merg
 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:
 
@@ -206,7 +218,7 @@ Install via pip:
 Install via conda:
 
 ```
-    conda install -c conda-forge custom-inherit 
+    conda install -c conda-forge custom-inherit
 ```
 
 or
@@ -264,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

@@ -143,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).
 
@@ -159,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/_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))

tests/metaclass_test.py

@@ -52,6 +52,10 @@ def absproperty(self):
 
 
 class Kid(Parent):
+    def __init__(self):
+        """kid"""
+        pass
+
     def kid_method(self):
         """kid"""
         pass
@@ -89,6 +93,12 @@ def test_sideeffect():
     assert signature(Kid.method) == signature(Parent.method)
 
 
+def test_special_method():
+    # by default, Kid.__init__ docstring should not inherit from its parent
+    assert isinstance(Kid().__init__, MethodType)
+    assert getdoc(Kid.__init__) == "kid"
+
+
 def test_method():
     assert isinstance(Kid().method, MethodType)
     assert getdoc(Kid.method) == "valid"
@@ -145,6 +155,10 @@ def prop(self):
 
 
 class Kid2(Parent2):
+    def __init__(self):
+        """kid"""
+        pass
+
     def kid_method(self):
         """kid"""
         pass
@@ -170,6 +184,12 @@ def test_sideeffect2():
     assert signature(Kid2.method) == signature(Parent.method)
 
 
+def test_special_method2():
+    # by default, Kid.__init__ docstring should not inherit from its parent
+    assert isinstance(Kid2().__init__, MethodType)
+    assert getdoc(Kid2.__init__) == "kid"
+
+
 def test_method2():
     assert isinstance(Kid2().method, MethodType)
     assert getdoc(Kid2.method) == "valid"
@@ -218,3 +238,22 @@ class Child(Mixin, Parent):
         getdoc(Child)
         == "This is mixin which does something.\n\nAttributes\n----------\nbar\n\nReturns\n-------\nfoo"
     )
+
+
+""" Include special method option"""
+
+@add_metaclass(DocInheritMeta(style=style, include_special_methods=True))
+class Parent3(object):
+    def __init__(self):
+        """"""
+        pass
+
+class Kid3(Parent3):
+    def __init__(self):
+        """kid"""
+        pass
+
+def test_special_method3():
+    # __init__ docstring should inherit from Parent3
+    assert isinstance(Kid3().__init__, MethodType)
+    assert getdoc(Kid3.__init__) == "valid"