sphinx icon indicating copy to clipboard operation
sphinx copied to clipboard

Viewcode: Support import paths that differ from the directory structure

Open ProGamerGov opened this issue 3 years ago • 2 comments

If the module import path used by users does not match the directory / file structure, import_lib's import_module function cannot find it.

Below is a basic example of where this failure occurs:

package/
    `__init__.py` # import package.subpackage1 as subpackage1
    subpackage1/
        `__init__.py` # from package.subpackage1.subpackage2 import module_1
        subpackge2/
            `__init__.py`
            module_1.py

Using the above directory / file structure, users import module1 via:

import package.subpackage1.module1

Sphinx is generally able to handle this sort of structure, except for the viewcode extension that uses the get_full_modname function from here: https://github.com/sphinx-doc/sphinx/blob/5.x/sphinx/util/init.py

That function specifically causes an error with the above example when importlib's import_module is run:

from importlib import import_module
module = import_module("package.subpackage1.module1") # Fails
# ModuleNotFoundError: No module named 'package.subpackage1.module1'

The exact path to the module however has no error:

from importlib import import_module
module = import_module("package.subpackage1.subpackage2.module1") # Works

Feature / Bugfix

This PR is my attempt at fixing the above import_module error by locating the exact path to the module, which is then used with import_module.

Currently this issue can be seen on projects where the viewcode extension is enabled, yet no source code link is created. Example: https://captum.ai/api/utilities.html#visualization

My solution utilizes importlib's __import__ function to find the directory module path to the object.

ProGamerGov avatar Aug 13 '22 16:08 ProGamerGov

@AA-Turner, @tk0miya let me know if I need to change anything for this PR to be merged

ProGamerGov avatar Aug 14 '22 15:08 ProGamerGov

@danieleades The conflicts have been resolved, so this PR is ready for merging

ProGamerGov avatar Aug 29 '22 17:08 ProGamerGov