Recognize a documented attribute of a module as non-imported.

[lokik]

Subject: To recognize better, whether a module attribute is imported or not.

Feature or Bugfix - It changes the behavior of the autosummary, so it is a breaking change,
but this change can or can not (depending on the point of view) be considered as a bugfix

Purpose

If an object of an imported class is instantiated in a module and it is assigned to a module attribute,
it has been so far always considered as imported. This results in not documenting some module members.

The behavior comes from the fact, that object.module attribute is inherited from its class
and the comparison of module attribute have been the way how to recognize imported
stuff.

Since there is probably no simple way how to find out whether an object
was imported or not, this pullrequest solve the issue partially.
If a module attribute is explicitly documented in the source file,
it is surely non-imported - thus, it is marked so.

[tk0miya]

LGTM with nits. Could you add a testcase for this, please?

[tk0miya]

Is this condition related to the __module__? I think this check should be separated to another condition.

[lokik]

I viewed it as "fix" for the the fact, that instances of user defined classes has __module__ property set to the module, where the class is defined, and not to the one where the object is instantiated. So from the original intent of the commit, yes, it is related, as it is an attempt to fix the false positive of the 'is-the-stuff-imported?' test.

But you are right, that you can consider it and define, that non-imported module attributes are just these, that have some docstring and thus made the condition separate (before the currently modified one). However, this IMHO would lead to further change in the autosummary behavior: so far the instantiated object without docstrings that has __module__ set to the module, where they are instantiated (e.g. if their class is defined in the same module) are considered as non-imported - and that would change.

So, this is maybe really a more systematic treating of the problem and thus maybe a better option? However, the resulting criterion would have no connection to "being imported" at all - in this case I would consider an introduction of a new option, something like "autosummary_only_documented_modules_attributes", and to treat the module attributes according to this new option, independently to the autosummary_imported_members option.

[tk0miya]

In autodoc, global variables having doc-comment are documented without :imported-members: option even if their __module__ value are different because they're considered as "locally defined variables".

class Foo:
    pass


#: a global variable having different __module__
var1 = int

#: a global variable having same __module__
var2 = Foo

So I think it's better to check the member has doc-comment or not first to determine imported flag.

if ('', name) in attr_docs:
  imported = False
elif inspect.ismodule(value):
  ...

[tk0miya]

Merged this into the 5.x branch (see #10428).

Thank you for your work!