Python Sphinx Autosummary: failed to import module

Question

I am trying to create autosummary using sphinx-autosummary for my python code which looks like as follows:

main
├───modA
|   ├───__init__.py
|   ├───modA.py
├───modB
|   ├───__init__.py
|   ├───modB.py
├───docs
|   ├───build
|   └───source
|       ├───refs
|       |   |───_autosummary
|       |   |───index.rst
|       |   |───modA.rst
|       |   |───modB.rst
|       ├───index.rst
|       ├───conf.py

As mentioned in Sphinx documentation, I inserted the abspath of my working directory, added sphinx.ext.autodoc to the list of extensions, and set autosummary_generate to True in conf.py .

import os
import sys
sys.path.insert(0, os.path.abspath('../..'))

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx.ext.autodoc',
    "sphinx.ext.autosummary", 
    'sphinx.ext.coverage', 
    'sphinx.ext.napoleon'
]

autosummary_generate = True

Next, within docs/index.rst , I added a reference to the refs/ folder.

.. toctree::
   :maxdepth: 2

   refs/index

The refs/index.rst has reference to modA.rst and modB.rst .

.. toctree::
   :maxdepth: 2

   modA
   modB

In modA.rst and modB.rst , I am trying to create autosummaries.

modA.rst

Attributes
~~~~~~~~~~
.. autosummary::
   :toctree: _autosummary

   modA.modA.create_job

modB.rst

Attributes
~~~~~~~~~~
.. autosummary::
   :toctree: _autosummary

   modB.modB.get_jobs

While the code is working for modA.rst , it fails for modB.rst . The error says,

failed to import 'modB.modB.get_jobs': no module named modB.modB.get_jobs

I tried putting .. currentmodule::modB and .. currentmodule::main before the autosummary, but with no success. I even tried putting .. module::modB and .. module::main before autosummary, but even that is not working. I searched a lot on the internet, but unable to understand why it's not working.

Edit-1 : Added __init__.py in both the folders.

Answer 1

I had a similar issue.

My reason of failed import error was that the module modA.modA , specified under .. autosummary:: directive, had imports of not installed libraries.

Attributes
~~~~~~~~~~
.. autosummary::
   :toctree: _autosummary

   modA.modA.create_job

But in general your reason for failed to import error can be different, because the function that imports modules from .. autosummary:: directive catches all errors and autosummary prints to output the same error message.

Here is the related issue on github https://github.com/sphinx-doc/sphinx/issues/7989

I suggest to import your modules modA.modA , modB.modB and see if there are any errors during importing.

Answer 2

I had similar issue in using Sphinx.

After some experiments, I suspect that the error message like failed to import XXX: no module named XXX does not necessarily mean the module XXX cannot be found. Instead, in my experiment, there is some error in importing XXX.

In my case, the module XXX itself is importing some package YYY that has not been installed. Since Sphinx import XXX in order to extract docstring, it found an error in this import attempt. After I removed that import YYY statement, I can successfully build the documentation.

Answer 3

I have the same problem with a large code base and it seems that when Sphinx can't handle an import statement it will just show some generic module import warning. Even when the package seems to be installed such warnings can occure.

The only workaround I found so far is using the autodoc_mock_imports in the conf.py for some specific libraries to mock specific libraries that Sphinx can't handle correctly.

Example: autodoc_mock_imports = ["flask", "flask_restx", "mongoengine", "model", "flask_jwt_extended"]