sphinx-build失败 - autodoc无法导入/查找模块

时间:2012-04-25 21:54:39

标签: python documentation python-sphinx

我正试图开始使用Sphinx并且似乎有无情的问题。

命令:docs/sphinx-quickstart

我回答所有问题,一切正常。

命令:docs/ls

一切看起来都很正常。结果:build Makefile source

命令:sphinx-build -d build/doctrees source build/html

似乎有效。我能够打开index.html文件并查看我想要的“shell”。

当我尝试将我的实际源代码作为source文件夹时,我遇到了问题。

命令:sphinx-build -d build/doctrees ../ys_utils build/html

结果:

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!

我是Sphinx的全新手,对这种文档来说相对较新。有人可以提供一些建议吗?

编辑:

我希望能够使用Makefile来处理这个问题。截至目前,我的项目中有两个文件夹。

nextgen/ls

docs ys_utils

我需要nextgen/docs/Makefileys_utils以及我将要拥有的所有其他模块生成HTML。

8 个答案:

答案 0 :(得分:74)

Autodoc无法找到您的模块,因为它们不在sys.path中。

您必须在sys.path的{​​{1}}中添加模块的路径。 查看conf.py的顶部(在导入conf.py之后),有一个sys语句,您可以对其进行调整。

顺便说一下:您可以使用Sphinx创建的sys.path.insert()来创建文档。 只需致电

Makefile

查看选项。

如果出现问题,请尝试:

make

在运行make clean 之前。

答案 1 :(得分:29)

conf.py

中的

只需添加项目文件夹的路径即可。

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

答案 2 :(得分:20)

听起来os.path.append()对于人们来说可行,但如果您按照conf.py模板,则会使用sys.path将模块路径插入os.path.insert(0, ...)的前面,只需添加额外的.

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

如果您已将sphinx项目设置为使用单独的buildsource目录,则该调用应改为:

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

答案 3 :(得分:3)

如果

  1. 模块根路径已在conf.py中正确设置
  2. __init__.py正确放置
  3. 第一种语法正确

并且您的autodoc仍然找不到模块...

可能是因为在您的python环境下不满足这些模块的依赖性。您将要检查所有导入语句是否在模块内正常工作。

答案 4 :(得分:1)

我想我第一次尝试将文件添加到toctree时就这样做了。我想是因为我省略了:maxdepth行和文件名之间的空行。

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

上面是我的index.rst文件。 stuff.rst与它位于同一目录中。

答案 5 :(得分:1)

我不知道为什么(在我的情况下,autodoc可能无法安装我的软件包),但是直到我明确包含所有包含路径模块的目录之后,我总是遇到module-not-found错误。

对于以下示例文件夹结构

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

我包括了

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

conf.py的开头,这样将添加所有涉及的目录。

答案 6 :(得分:0)

我遇到了同样的错误,但这是由与其他答案完全不同的原因造成的。

我的.. automethod:: mymodule.func指令实际上应该是:

.. automethod:: mymodule::func`

答案 7 :(得分:-1)

Sphinx不是python3兼容,运行__import__(module_name) importlib.import_module(module_name)都可以在我的翻译中使用,但不能在sphinx中使用。

我试过检查sphinx的主分支,在Makefile中将我的解释器更改为python3.4,并且在3.x系列中删除的模块上出现错误。您可以在此处查看我的问题报告:

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