关于python：sphinx-build失败-autodoc无法导入/查找模块


sphinx-build fail - autodoc can't import/find module

我正在尝试开始使用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

结果：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
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。

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

您必须在conf.py的sys.path中包括模块的路径。
查看conf.py的顶部(在导入sys之后)，有一个sys.path.insert()语句，您可以对其进行调整。

顺便说一句：您可以使用Sphinx创建的Makefile创建文档。
只需致电

1
make

以查看选项。

如果在尝试之前出了点问题：

1
make clean

在运行make html之前。

相关讨论

这听起来像os.path.append()对于人们来说工作正常，但是如果您遵循conf.py模板，则可以使用os.path.insert(0, ...)将模块路径插入sys.path的开头，并添加一个额外的

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

如果已将sphinx项目设置为使用单独的build和source目录，则该调用应为：

1
sys.path.insert(0, os.path.abspath('../..'))
相关讨论

conf.py

中的

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

1
sys.path.append('/home/workspace/myproj/myproj')
相关讨论

如果

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

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

    可能是因为在您的python环境下不满足那些模块的依赖关系。您将要检查所有导入语句是否在模块中都起作用。

    相关讨论

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

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

    1
    .. automethod:: mymodule::func`

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

    对于以下示例文件夹结构

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    project_dir
    |- setup.py
    |- src
    |  |- __init__.py
    |  |- source1.py
    |  |- sub_project
    |     |- __init__.py
    |     |- source2.py
    |- docs
        |- conf.py
        |- source
        |  |- index.rst
        |- _build

    我包括了

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

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

    我想我是第一次尝试将文件添加到toctree时执行此操作。我认为这是因为我在：maxdepth行和文件名之间留了空白行。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    .. 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和它驻留在同一目录中。

    相关讨论

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

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

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