sphinx-build fail - autodoc can't import/find module

Question

I'm trying to get started with Sphinx and seem to have relentless problems.

Command: docs/sphinx-quickstart

I answer all the questions and everything works fine.

Command: docs/ls

Everything looks normal. Result: build Makefile source

Command: sphinx-build -d build/doctrees source build/html

It seems to work. I was able to open the index.html file and see a "shell" of what I'm wanting.

When I try and put my actual source code as the source folder I run into problems.

Command: sphinx-build -d build/doctrees ../ys_utils build/html

Result:

Making output directory...
Running Sphinx v1.1.3
loading pickled environment... not yet created
No builder selected, using default: html
loading intersphinx inventory from http://docs.python.org/objects.inv...
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
Traceback (most recent call last):                                                                                               
  File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.1.3-py2.6.egg/sphinx/ext/autodoc.py", line 321, in import_object
    __import__(self.modname)
ImportError: No module named ys_utils
Traceback (most recent call last):
  File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.1.3-py2.6.egg/sphinx/ext/autodoc.py", line 321, in import_object
    __import__(self.modname)
ImportError: No module named ys_utils.test_validate_ut
Traceback (most recent call last):
  File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.1.3-py2.6.egg/sphinx/ext/autodoc.py", line 321, in import_object
    __import__(self.modname)
ImportError: No module named ys_utils.git_utils
Traceback (most recent call last):
  File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.1.3-py2.6.egg/sphinx/ext/autodoc.py", line 321, in import_object
    __import__(self.modname)
ImportError: No module named setup.setup

/home/ricomoss/workspace/nextgen/ys_utils/ys_utils.rst:4: WARNING: autodoc can't import/find module 'ys_utils', it reported error: "No module named ys_utils", please check your spelling and sys.path
/home/ricomoss/workspace/nextgen/ys_utils/ys_utils.rst:10: WARNING: autodoc can't import/find module 'ys_utils.test_validate_ut', it reported error: "No module named ys_utils.test_validate_ut", please check your spelling and sys.path
/home/ricomoss/workspace/nextgen/ys_utils/ys_utils.rst:12: WARNING: don't know which module to import for autodocumenting u'UnitTests' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
/home/ricomoss/workspace/nextgen/ys_utils/ys_utils.rst:18: WARNING: autodoc can't import/find module 'ys_utils.git_utils', it reported error: "No module named ys_utils.git_utils", please check your spelling and sys.path
/home/ricomoss/workspace/nextgen/ys_utils/ys_utils.rst:24: WARNING: autodoc can't import/find module 'setup.setup', it reported error: "No module named setup.setup", please check your spelling and sys.path
WARNING: master file /home/ricomoss/workspace/nextgen/ys_utils/index.rst not found
looking for now-outdated files... none found
pickling environment... done
checking consistency... /home/ricomoss/workspace/nextgen/ys_utils/ys_utils.rst:: WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [ 50%] index                                                                                                   
Exception occurred:
  File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.1.3-py2.6.egg/sphinx/environment.py", line 1213, in get_doctree
    f = open(doctree_filename, 'rb')
IOError: [Errno 2] No such file or directory: '/home/ricomoss/workspace/nextgen/docs/build/doctrees/index.doctree'
The full traceback has been saved in /tmp/sphinx-err-jjJ7gM.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
Either send bugs to the mailing list at <http://groups.google.com/group/sphinx-dev/>,
or report them in the tracker at <http://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!

What is wrong, and how can I fix it?

Edit:

I'd like to be able to use a Makefile to handle this. As of now I have two folders in my project.

nextgen/ls

docs ys_utils

I need nextgen/docs/Makefile to generate the HTML for ys_utils and all other modules I'm going to have.

Askance

Answer 1

Autodoc can't find your modules, because they are not in sys.path.

You have to include the path to your modules in in the sys.path in your conf.py. Look at the top of your conf.py (just after the import of sys), there is a sys.path.insert() statement, which you can adapt.

By the way: you can use the Makefile created by Sphinx to create your documentation. Just call

make

to see the options.

If something went wrong before try:

make clean

before running make html.

Settling

In conf.py, add print(sys.executable) My sphinx-build was invoking py-3.8 but my venv was py-3.7. – Teagan

Hm, I have an external dependency installed via pip which I can import without problems when running Python in the command line. But sphinx does not pick it up and throws and error "no module..". sys.executable points to the correct Python installation. What could be the problem? – Fard

Answer 2

solution

It sounds like os.path.append() is working OK for folks, but if you follow the conf.py template, you would insert the module path to the front of sys.path using os.path.insert(0, ...), and just add an extra .

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

If you have setup your sphinx project to use separate build and source directories, that call should instead be:

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

about sys.path

To run python code, the python interpreter needs to know where it is. With the sphinx config being a python script, it's location needs to be made known, which is done by adding it the the sys.path variable using the insert method (see the docs on module search path).

The path added to sys.path in this case is a "relative" path, which is specified using dots. This is a general way of specifying the path, which allows the code to be moved and still point correctly to the correct path in your codebase.

. - current path of the conf.py

.. - parent path of the conf.py

../.. - parent of the parent path, etc.

I use linux, so directories are specified with a forward slash, but a cross-platform method for specifying parent directories can be acheived with pathlib.

from pathlib import Path

parent = Path(__file__).parent
parents_parent = Path(__file__).parents[1]

Crease

for some weird reason os.path.abspath(os.path.split(__file__)[0] + '../../') does not work while os.path.abspath('../..')) does work. I have no idea why. – Counterspy

Could you explain what sys.path.insert(0, os.path.abspath('..')) really does? Does it point to local dependencies/code so not stuff installed via pip? – Fard

@FelixB. perhaps it is the trailing forward slash. – Crease

@CGFoX I've added some commentary on sys.path. – Crease

Answer 3

in conf.py

just add the path to your project folder.

sys.path.append('/home/workspace/myproj/myproj')

Municipalize

Path hard-coding isn't the best thing you can do with your conf.py. – Jargon

If you have a project structure like /app, /docs, ... you might to use sys.path.append(os.path.join(os.path.dirname(__name__), '..')) and then use .. automodule:: app in your .rst-file. – Paley

Answer 4

I don't know why (maybe in my case autodoc couldn't install my package), but I always got module-not-found errors until I explicitly included all directories containing modules to the path.

For the following example folder structure

project_dir
|- setup.py
|- src
|  |- __init__.py
|  |- source1.py
|  |- sub_project
|     |- __init__.py
|     |- source2.py 
|- docs
    |- conf.py
    |- source
    |  |- index.rst
    |- _build       

I included

for x in os.walk('../../src'):
  sys.path.insert(0, x[0])

to the beginning of conf.py such that all involved directories would be added.

Defoliate

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

Answer 5

If

1. module root path is correctly set in conf.py
2. __init__.py is placed correctly
3. rst syntax is correct

and your autodoc still cannot find the modules...

It may be because the dependencies of those modules are not satisfied under your python environment. You will want to check if all the import statements are working within the modules.

Tadd

I don't get why sphinx needs dependencies, is it because of the possibility of having tests within docstrings? Can this be avoided (I don't need any package, I just want sphinx to parse docstring to html). – Mcclendon

If you don't want to import these dependencies use autodoc_mock_imports in your conf.py file: sphinx-doc.org/en/master/usage/extensions/… – Beveridge

Answer 6

I got this same error but it was caused by a completely different reason than explained in the other answers.

My .. automethod:: mymodule.func directive should actually have been:

.. automethod:: mymodule::func

See the New in version 1.3 section in the autoclass documentation.

Going

Answer 7

i add the following line at the beggining of file conf.py:

import os
import sys
sys.path.insert(0, os.path.abspath('..'))
sys.path.append(os.path.abspath(
    os.path.join(__file__, "../../src")
))

my project has the next structure:

project_dir
|- setup.py
|- src
|  |- __init__.py
|  |- ....
|- docs
    |- conf.py
    |- ...

Mizuki

Answer 8

I think I did this the first time I tried to add a file to the toctree. I think it was because I left out the blank line between the :maxdepth line and the file name.

.. Animatrix Concepts documentation master file, created by
   sphinx-quickstart on Thu Mar 22 18:06:15 2012.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to Animatrix Concepts documentation!
============================================

Contents:

.. toctree::
   :maxdepth: 2

   stuff


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Above is my index.rst file. stuff.rst resides in the same directory as it.

Snapshot

Where would this go? I have index.rst in /docs/source and /ys_utils. I'm guessing this should be in the docs version? I'm just using the default index.rst file that was created with sphinx-quickstart. – Askance

-1 as from the traceback it seems clear that the modules are not in sys.path, so autodoc cn't find them. The .rst files are found. – Settling

Answer 9

The trick that I use to "skip" the finding or importing module error.

If the cong.py file, just below the sys.path few lines of code, add this line:

autodoc_mock_imports = ['module_with_error1', 'module_with_error2', ....]

By replacing whats inside the bracket with the module that the file couldn't find/import, worked for me for both internal and external modules.

Torre

Answer 10

I had the same issue with module imports in my Python project that took me weeks to resolve.

this was my folder structure.

project_dir/
│
├── setup.py
│
├── src/
│   ├── __init__.py
│   ├── module1/
│   │   └── __init__.py
│   └── module2/
│       └── __init__.py
│
└── docs/
    ├── conf.py
    └── ...

Initially, my src/__init__.py file was empty because I didn't think there was a need to add anything there. However, I discovered that importing my modules into the src/__init__.py file resolved the importing issues.

Here's how I modified src/__init__.py:

from .module1 import *
from .module2 import *

I'm not sure why it worked, still looking for a proper answer, will update once I find a satisfactory answer. But hope this helps.

Lymn

Answer 11

You can use Pweave and noweb formatting to generate rst documents that include the output of the code embedded in them. Basically, you write your rst file, with python code embedded in marked chunks like this:

<<echo=False>>=
print("some text that will appear in the rst file")
@

and Pweave will execute those chunks, and replace them with their output in a resulting rst file, which you can then use with sphinx. See the Pweave reST example for more details of how it looks.

Factor

Answer 12

A lot of solutions in the thread are discussed in the right direction. For me, the command on the official docs was helpful.

import pathlib
import sys
sys.path.insert(0, pathlib.Path(__file__).parents[2].resolve().as_posix())

Barretter