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.py的sys.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系列中删除的模块上出错。 你可以在这里看到我的问题报告：
您可以使用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项目来使用单独的bulid和source目录，那么调用应该是：
sys.path.insert(0, os.path.abspath('../..'))
