Allow finer-grained control over display of inherited members

[td-anne]

When we generate documentation for classes, we have two situations:

1. We wrote a base class with various attributes and methods that we want exposed to the user, and we would like the inherited members to be displayed in the derived classes.
2. We derived a class from Exception or Enum or some other generic class (not necessarily in the python standard library) and thus inherit a heap of methods that are not of interest to the user; we would like to suppress display of inherited members.

If a given project contains only one of these categories, we can select inherited-members or not as appropriate. But if we have both situations in the same project, there does not seem to be a way we can get the desired behaviour.

Ideally I would like to be able to set something on the class definition (perhaps in the class docstring?) that would control whether this class showed inherited members. (Perhaps this could even work recursively up the inheritance graph, so that deriving from a class that didn't show its inherited members I could show members inherited from that class but not its superclasses.)

Sadly autoapi-skip-member does not provide enough information (as far as I can tell) to inspect the (docstring of the) class that the object is a member of. It does at least provide obj.inherited, which is a key piece of information.

I suppose I could maintain a list of classes that did or did not want their inherited members documented, and perhaps I could use the fully qualified name to check whether objects in autoapi-skip-member were members of one of these classes. Having to maintain this list separately from the classes being documented seems error-prone.

[AWhetter]

You'd be using undocumented parts of AutoAPI, but I think you can achieve what you're looking for.
obj has an attribute obj, which is a dictionary of values that it gets from the parser. One of those values, original_path, is set for imported members and contains the fully qualified name of where this member was imported from.
If the fully qualified name of the original location isn't enough, then the attribute app.env.autoapi_all_objects is a dictionary of fully qualified names to PythonPythonMapper objects (the same objects that get passed into autoapi-skip-member.
So you could try configuring a autoapi-skip-member hook to do something like the following:

def skip_some_inherited_members(app, what, name, obj, skip, options):
    if not obj.inherited:
        return None

    original_path = obj.obj.get("original_path")
    if not original_path:
        return None

    # If you want to inspect the original object
    #original_obj = app.env.autoapi_all_objects.get(original_path)
    #if not original_obj:
    #    return None

    # If checking the original location is enough.
    # For example to ignore inherited attributes from enums.
    #if original_obj.startswith("enum."):
    #    return False

    return None

[AWhetter]

We currently don't document much of the API of objects. They get used in templates and in hooks like this. So by not documenting that bit of the API, we make use cases like this more difficult to navigate. So I think that the right solution here is this documentation.

[AWhetter]

Actually, original_path is only set for imported members. Not inherited ones. So I don't think that my suggested workaround will work after all.
Furthermore, the implementation will require setting original_path for inherited members, and exposing this publicly.

[cpascual]

Hi, I came to this issue because I am exactly in the situation described by @td-anne . While the use of autoapi-skip-member would be nice (provided that the original_path info is provided), I find @td-anne 's suggestion much more convenient (at least for my use-case):

Ideally I would like to be able to set something on the class definition (perhaps in the class docstring?) that would control whether this class showed inherited members.

@AWhetter : is there some fundamental objection against that type of solution?