问题:sphinx-build失败-autodoc无法导入/查找模块
我正在尝试开始使用Sphinx,似乎遇到了很多问题。
命令: docs/sphinx-quickstart
我回答所有问题,一切正常。
命令: docs/ls
一切看起来都很正常。结果:build Makefile source
命令: sphinx-build -d build/doctrees source build/html
似乎有效。我能够打开index.html文件,并看到我想要的“外壳”。
当我尝试将实际的源代码作为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/Makefile
为ys_utils
将要拥有的所有其他模块生成HTML 。
回答 0
Autodoc找不到您的模块,因为它们不在中sys.path
。
你必须包括在路径到您的模块sys.path
在你的conf.py
。查看您的顶部conf.py
(在导入之后sys
),有一条sys.path.insert()
语句可以调整。
顺便说一句:您可以使用Makefile
Sphinx创建的创建文档。刚打电话
make
查看选项。
如果出现问题,请尝试以下操作:
make clean
之前运行make html
。
回答 1
听起来os.path.append()
对所有人来说还可以,但是如果您遵循conf.py
模板,则可以将模块路径插入sys.path
using 的前面os.path.insert(0, ...)
,然后添加一个额外的.
import os
import sys
sys.path.insert(0, os.path.abspath('..'))
如果您已经安装你的sphinx
项目中使用单独build
和source
目录,该呼叫应改为:
sys.path.insert(0, os.path.abspath('../..'))
回答 2
在 conf.py
只需将路径添加到您的项目文件夹。
sys.path.append('/home/workspace/myproj/myproj')
回答 3
如果
- 在conf.py中正确设置了模块根路径
__init__.py
放置正确- 第一个语法正确
而且您的autodoc仍然找不到模块…
可能是因为在您的python环境下无法满足这些模块的依赖性。您将要检查所有导入语句是否在模块内正常工作。
回答 4
我想我是第一次尝试将文件添加到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
我遇到了同样的错误,但是它是由与其他答案完全不同的原因引起的。
我的.. automethod:: mymodule.func
指令实际上应该是:
.. automethod:: mymodule::func`
回答 6
您可以使用Pweave和noweb格式生成第一个文档,其中包括嵌入其中的代码的输出。基本上,您编写第一个文件,并在标记的块中嵌入python代码,如下所示:
<<echo=False>>=
print("some text that will appear in the rst file")
@
然后Pweave将执行这些块,并在输出的第一个文件中将其替换为输出,然后可将其与sphinx一起使用。有关其外观的更多详细信息,请参见Pweave reST示例。