Ignore inherited docstring

[Voyz]

Is there any way to prevent inheriting docstrings? This was introduced in fca36aa based on #203, yet there are cases when this is an unwanted behaviour.

When inheriting some simple classes the resulting doc contains an unwanted docstring that's inherited:

class MyEnum(Enum):
    """This is my enum"""

Will generate the following doc:

class MyEnum
    Bases: enum.Enum
    
    This is my enum

    Create and return a new object. See help(type) for accurate signature.

That last line is unnecessary and misleading. It is brought in from the Python builtin type.__new__ and is displayed in all objects that don't contain a bespoke __init__ or __new__ with a docstring.

I'm guessing that this behaviour could be prevented by configuring the autoapi_python_class_content to class, but I wouldn't want to do that given that elsewhere I define all of my docstrings in __init__s

Would be amazing if there was a configuration option in autoapi_options that could prevent this behaviour. Even more so - it would be ideal if there was some local pragma that could be added to a docstring that would prevent this on case-by-case basis, such as:

class MyEnum(Enum):
    """
    This is my enum
    
    #pragma: ignore_inheritance
    """

Autoapi: 1.4.0
Python: 3.7

(btw. thanks for this incredible library! Really well done!)

[AWhetter]

This seems like a reasonable suggestion to me. You're right that setting autoapi_python_class_content to "class" would fix this issue, but I can see why you wouldn't want the object.__new__ docstring included so adding an option to ignore it makes sense to me.

[AWhetter]

To any new contributors looking to implement this issue, the get_func_docstring() function added in fca36aa will need to take a new parameter that ignores object.__new__ when an option (defined in

sphinx-autoapi/autoapi/extension.py

Line 282 in 5bb4ff2

def setup(app):

) is set.

[attilaviniczai]

Hi, I have taken a look at this issue. During the effort to reproduce said issue with integration tests, I have discovered the following:

1. The issue is not encountered when deriving classes from object
2. The issue is encountered when deriving from type
3. The issue is encountered when deriving from enum.Enum, as enum.Enum also derives from type

Based on the above I have came to the conclusion that the issue can be prevented by adding __builtins__.type and builtins.type to the following list:

sphinx-autoapi/autoapi/mappers/python/astroid_utils.py

Line 600 in f986f02

if base.qname() in ("__builtins__.object", "builtins.object"):

Now my question is: should ignoring type.__new__.__doc__ from class docstring construction be controlled by an option, or should this be the default behaviour instead? I am asking this because I do not believe users would want type.__new__.__doc__ included in their class documentation, however this is only my newbie guess.

[Voyz]

Thank you for looking into it @attilaviniczai. I think ignoring type.__new__.doc__ by default would be more in line with the expected behaviour. My reasoning is that when documenting an object, we would want the documentation to precisely describe how our implementation works, not how a built-in Python object works - not to mention the inherited docstring is quite redundant.

One more thing I'd add, is that when inheriting from Exceptions a similar behaviour is present, yet they don't inherit from neither type nor enum, therefore it seems to be a broader scope than only these two.

[Voyz]

Thanks @AWhetter! 👏