CODEWITHSUNDEEP
pythonpython-sphinx
Milan Jain
Milan Jain

Reputation: 519

Python Sphinx Autosummary: failed to import module

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.

Upvotes: 12

Views: 8964

Answers (3)

Me7e0r
Me7e0r

Reputation: 107

It seems that when Sphinx can't handle a python import it will show the generic module import warning (".. no module named ...") as you mentioned. It seems that this warning can even occur when all imported python package are correctly installed in the environment and it just means that something could not be imported.

A workaround to get rid of this warnings is to mock external python libraries by using the autodoc_mock_imports in the conf.py file of Sphinx.

For example:

import flask
import mongoengine
...
# your python code

Example conf.py with mocking flask: autodoc_mock_imports = ["flask", "mongoengine"]

In this case Sphinx will ignore these imports and autosummary may be able to build the summary correctly without any errors.

To be more specific to your case: It could be that your python file 'modB.modB' contains an import statement that Sphinx can't handle and that you either need to install the python package correctly or to mock the specific libraries imported in the modB.modB file.

Upvotes: 5

Jianing
Jianing

Reputation: 318

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.

Upvotes: 15

vilozio
vilozio

Reputation: 322

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.

Upvotes: 2

Related Questions