sphinx-build fail - autodoc can't import/find module
Solution 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
.
Solution 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]
Solution 3
in conf.py
just add the path to your project folder.
sys.path.append('/home/workspace/myproj/myproj')
Solution 4
If
- module root path is correctly set in conf.py
__init__.py
is placed correctly- 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.
Solution 5
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.
Rico
I am a site reliability engineer at Verizon Digital Media Services. I contribute to the Uplynk product, which is responsible for playback management for online video assets used by Verizon Digital Media Services customers. (i.e. ESPN, ABC, Disney, etc) I've created and consumed web services worldwide. Django is my web framework of choice but have experience in other languages, frameworks and technologies including Postgres, MySQL, MongoDB, Celery, RabbitMQ and much more.
Updated on February 05, 2022Comments
-
Rico over 2 years
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!
I am a complete newbie to Sphinx and relatively new to this kind of documentation. Can anyone offer some suggestions?
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 forys_utils
and all other modules I'm going to have. -
Rico about 12 yearsWhere would this go? I have
index.rst
in/docs/source
and/ys_utils
. I'm guessing this should be in thedocs
version? I'm just using the defaultindex.rst
file that was created withsphinx-quickstart
. -
bmu about 12 years-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. -
firegurafiku almost 9 yearsPath hard-coding isn't the best thing you can do with your
conf.py
. -
fnkr almost 9 yearsIf you have a project structure like
/app
,/docs
, ... you might to usesys.path.append(os.path.join(os.path.dirname(__name__), '..'))
and then use.. automodule:: app
in your.rst
-file. -
cglacet about 4 yearsI 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).
-
filip stepniak about 4 yearsIf you don't want to import these dependencies use autodoc_mock_imports in your conf.py file: sphinx-doc.org/en/master/usage/extensions/…
-
Felix B. over 3 yearsfor some weird reason
os.path.abspath(os.path.split(__file__)[0] + '../../')
does not work whileos.path.abspath('../..'))
does work. I have no idea why. -
JimB over 3 yearsIn
conf.py
, addprint(sys.executable)
My sphinx-build was invoking py-3.8 but my venv was py-3.7. -
CGFoX almost 3 yearsCould you explain what
sys.path.insert(0, os.path.abspath('..'))
really does? Does it point to local dependencies/code so not stuff installed viapip
? -
CGFoX almost 3 yearsHm, 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? -
ryanjdillon almost 3 years@FelixB. perhaps it is the trailing forward slash.
-
ryanjdillon almost 3 years@CGFoX I've added some commentary on sys.path.