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

我试图开始与狮身人面像,似乎有无情的问题。

命令: 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! 

我是狮身人面像的一个完整的新手,这种文档相对较新。 谁能提供一些build议?

编辑:

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

nextgen/ls

docs ys_utils

我需要nextgen/docs/Makefile来为ys_utils和所有其他模块生成HTML。

Autodoc无法find您的模块,因为它们不在sys.path

您必须在conf.pysys.path中包含模块的path。 查看conf.py的顶部(刚刚导入sys ),有一个sys.path.insert()语句,您可以调整它。

顺便说一下:您可以使用Sphinx创build的Makefile创build文档。 打电话

 make 

看到选项。

如果尝试之前出现问题:

 make clean 

在运行之前make html

conf.py

只需将path添加到您的项目文件夹。

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

我想我是第一次尝试添加一个文件到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驻留在同一个目录中。

狮身人面像是不是很python3兼容,运行__import__(module_name) importlib.import_module(module_name)都在我的解释器,但不是在狮身人面像。

我试着检查出狮身人面像的主分支,在Makefile中将我的解释器改为python3.4,并在3.x系列中删除的模块上出错。 你可以在这里看到我的问题报告:

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

您可以使用Pweave和noweb格式生成第一个包含embedded代码的输出的文档。 基本上,你写下你的第一个文件,python代码embedded标记块如下:

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

Pweave将执行这些块,并将它们的输出replace为所得到的第一个文件,然后您可以使用它与狮身人面像。 请参阅Pweave reST示例了解更多细节。

我试图使用autodoc来logging我的狮身人面像代码,但它会跳过我的一个文件,因为我没有在该文件中创build一个类。 以下是这个文件最初的样子:

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

这个文件永远不会被sphinx成功logging。 为了得到它的logging,我必须做到以下几点:

 """ 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() 

所以,Sphinx似乎要求你把所有的文件都包装在一个类中,以便logging下来。 希望有帮助,因为我花了数小时试图弄清楚为什么狮身人面像不logging

这听起来像os.path.append()工作正常,但如果你遵循conf.py模板,你可以使用os.path.insert(0, ...)插入模块path到sys.path的前面os.path.insert(0, ...) ,只需添加一个额外的.

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

如果你已经设置你的sphinx项目来使用单独的bulidsource目录,那么调用应该是:

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