Sphinx-build crash - autodoc cannot import / find module

Question

I am trying to get started with Sphinx and seem to be having unforgiving problems.

Command: docs/sphinx-quickstart

I answer all questions and everything works fine.

Command: docs/ls

Everything looks fine. Result: build Makefile source

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

It seems to have worked. I was able to open the index.html file and see the “shell” of what I need.

When I try to set the 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 documentation. Can anyone suggest some suggestions?

Edit:

I would like to use a Makefile for this. At the moment, I have two folders in my project.

nextgen/ls

docs ys_utils

I need nextgen/docs/Makefile to generate HTML for ys_utils and all the other modules that I will have.

Answer 1

Autodoc cannot find your modules because they are not in sys.path .

You must specify the path to your modules in sys.path in conf.py Look at the top of conf.py (immediately after importing sys ), there is a sys.path.insert() statement that you can adapt.

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

 make 

to view the options.

If something went wrong before you try:

 make clean 

before running make html .

Answer 2

in conf.py

just add the path to the project folder.

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

Answer 3

It seems that os.path.append() works fine for people, but if you follow the conf.py pattern, you will insert the module path at the beginning of sys.path using os.path.insert(0,...) and just add extra

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

If you configured your sphinx project to use separate build and source directories, this call should be as follows:

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

Answer 4

I think I did this the first time I tried to add a file to toctree. I think this happened because I left an empty line between the line: maxdepth 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 is in the same directory as it.

Answer 5

You can use Pweave and noweb formatting to generate the first documents containing the output of the code embedded in them. Basically, you write your first file, python code is embedded in the marked snippets as follows:

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

and Pweave will execute these fragments and replace them with its result in the resulting first file, which you can then use with sphinx. For more on how this looks, see Pweave reST .

Answer 6

I tried using autodoc to document my sphinx code, but it will skip one of my files because I did not create a class in this file. Here's what the file originally looked like:

 """ testing autodoc - this should be first line in doc """ import simulator world = simulator.simulator() #some more code... 

This file will never be successfully registered with sphinx. To get the documentation, I had to do the following:

 """ testing autodoc - this should be first line in doc """ import simulator class runme(): def __init__(self): world = simulator.simulator() #some more code... if __name__ == "__main__": runme() 

So it seems that Sphinx requires you to wrap all your files in a class in order to get them documented. hope this helps because i spent hours trying to figure out why the Sphinx didn't document

Answer 7

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

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

 .. automethod:: mymodule::func' 

Answer 8

Sphinx is not very compatible with python3 , __import__(module_name) works, and importlib.import_module(module_name) works both in my interpreter and not in sphinx.

I tried checking the main sphinx branch, changed my interpreter to python3.4 in the Makefile and got errors in the modules that were removed in the 3.x series. You can see my problem report here:

https://github.com/sphinx-doc/sphinx/issues/2046