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

问题: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/Makefileys_utils将要拥有的所有其他模块生成HTML 。

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 <http://groups.google.com/group/sphinx-dev/>,
or report them in the tracker at <http://bitbucket.org/birkenfeld/sphinx/issues/>. 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.


回答 0

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

你必须包括在路径到您的模块sys.path在你的conf.py。查看您的顶部conf.py(在导入之后sys),有一条sys.path.insert()语句可以调整。

顺便说一句:您可以使用MakefileSphinx创建的创建文档。刚打电话

make

查看选项。

如果出现问题,请尝试以下操作:

make clean

之前运行make html

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.


回答 1

听起来os.path.append()对所有人来说还可以,但是如果您遵循conf.py模板,则可以将模块路径插入sys.pathusing 的前面os.path.insert(0, ...),然后添加一个额外的.

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

如果您已经安装你的sphinx项目中使用单独buildsource目录,该呼叫应改为:

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

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

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

回答 2

conf.py

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

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

in conf.py

just add the path to your project folder.

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

回答 3

如果

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

而且您的autodoc仍然找不到模块…

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

If

  1. module root path is correctly set in conf.py
  2. __init__.py is placed correctly
  3. rst syntax is correct

and your autodoc still cannot find the modules…

It may be because the dependencies of those modules are not satisfied under your python environment. You will want to check if all the import statements are working within the modules.


回答 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和它驻留在同一目录中。

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.


回答 5

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

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

.. automethod:: mymodule::func`

I got this same error but it was caused by a completely different reason than explained in the other answers.

My .. automethod:: mymodule.func directive should actually have been:

.. automethod:: mymodule::func`

回答 6

您可以使用Pweave和noweb格式生成第一个文档,其中包括嵌入其中的代码的输出。基本上,您编写第一个文件,并在标记的块中嵌入python代码,如下所示:

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

然后Pweave将执行这些块,并在输出的第一个文件中将其替换为输出,然后可将其与sphinx一起使用。有关其外观的更多详细信息,请参见Pweave reST示例

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:

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