Update doc for import discovery and qualified module names

[akamat10]

Type of Changes

	Type
✓	📜 Docs

Description

Refs #9915

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 95.80%. Comparing base (4c5393f) to head (e31ad17).
Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #9949   +/-   ##
=======================================
  Coverage   95.80%   95.80%           
=======================================
  Files         174      174           
  Lines       18940    18940           
=======================================
  Hits        18146    18146           
  Misses        794      794           

[akamat10]

Don't think changelog needs to be updated for docs based on my understanding.

[Pierre-Sassoulas]

I feel like this is a great doc after a dive in what exactly the code is doing, but at the same time this so close to being a description of what the code is doing that it's going to be out of sync fast if we ever change the code, that I'm not sure we should add it to the doc. Or maybe with a warning to upgrade the doc in the code ? Waiting for another maintainer opinion about this.

Is another way to do import discovery and work with qualified module name is simpler and make more sense to you @akamat10 ? If so maybe we could change to it directly.

[akamat10]

Thank you for going through this. It does require reading through the code :) to know it is correct. Mypy docs for reference where they describe their import discovery. The second option ie default in the doc is very similar to what pylint does if source-roots isn't specified. https://mypy.readthedocs.io/en/stable/running_mypy.html#mapping-file-paths-to-modules

Personally I think something like this ought to be in the user guide and leaving it out makes it difficult to understand what is going on. The user may not know where the code is where this is happening. If the logic changes, we should update the doc. I am ok with documenting in the code that the doc should change to reflect it.

Is another way to do import discovery and work with qualified module name is simpler and make more sense to you @akamat10 ? If so maybe we could change to it directly.

I assume you mean changing the current logic, right? I think source-root option comes closest in being clean and being able to control to make it to make it similar to how Python works. I have proposed an alteration in #9955 to simplify it. I would still document after changing the behavior so that the user knows.