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

问题:

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 , or report them in the tracker at . 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 for ys_utils and all other modules I'm going to have.

回答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.

回答2:

in conf.py

just add the path to your project folder.

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

回答3:

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.

回答4:

Sphinx is not very python3 compatible, running __import__(module_name) AND importlib.import_module(module_name) both work in my interpreter, but not in sphinx.

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

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

回答5:

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:

>= 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.

回答6:

I tried to use autodoc to document my sphinx code, but it would skip over one of my files because I didn't make a class within that file. Here's what the file originally looked something like this:

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

This file would never successfully get documented by sphinx. To get it to be documented, 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 like Sphinx requires you to wrap all your files up in a class to get them documented. hope that helps, cause I spent hours trying to figure out why Sphinx wasn't documenting

回答7:

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 bulid and source directories, that call should instead be:

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

文章来源: sphinx-build fail - autodoc can't import/find module