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

【问题标题】：sphinx-build fail - autodoc can't import/find modulesphinx-build 失败 - autodoc 无法导入/查找模块
【发布时间】：2012-05-06 15:40:12
【问题描述】：

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

【问题讨论】：

标签： python python-sphinx autodoc

【解决方案1】：

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

您必须在sys.path 中的conf.py 中包含模块的路径。看看你的conf.py 的顶部（在sys 的导入之后），有一个sys.path.insert() 声明，你可以适应它。

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

make

查看选项。

如果在尝试之前出现问题：

make clean

在运行make html之前。

【讨论】：

在 conf.py 中添加 print(sys.executable) 我的 sphinx-build 调用的是 py-3.8，但我的 venv 是 py-3.7。
嗯，我通过pip 安装了一个外部依赖项，在命令行中运行 Python 时可以毫无问题地导入它。但是 sphinx 没有捡起它并抛出错误“no module..”。 sys.executable 指向正确的 Python 安装。可能是什么问题？

【解决方案2】：

解决方案

听起来os.path.append() 对人们来说可以正常工作，但如果您遵循conf.py 模板，您将使用os.path.insert(0, ...) 将模块路径插入sys.path 的前面，然后添加一个额外的@987654326 @

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

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

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

关于 sys.path ...

要运行 python 代码，python 解释器需要知道它在哪里。由于 sphinx 配置是一个 python 脚本，因此需要知道它的位置，这是通过使用 insert 方法将其添加到 sys.path 变量来完成的（请参阅module search path 上的文档）。

在这种情况下，添加到sys.path 的路径是“相对”路径，使用点指定。这是一种指定路径的通用方式，它允许移动代码并仍然正确指向代码库中的正确路径。

. - conf.py 的当前路径

.. - conf.py 的父路径

../.. - 父路径的父级等

我用的是linux，所以目录是用正斜杠指定的，但是用pathlib可以实现指定父目录的跨平台方法。

from pathlib import Path

parent = Path(__file__).parent
parents_parent = Path(__file__).parents[1]

【讨论】：

出于某种奇怪的原因，os.path.abspath(os.path.split(__file__)[0] + '../../') 不起作用，而 os.path.abspath('../..')) 起作用。我不知道为什么。
您能解释一下sys.path.insert(0, os.path.abspath('..')) 的真正作用吗？它是否指向本地依赖项/代码而不是通过pip 安装的东西？
@FelixB。也许它是尾部的正斜杠。
@CGFoX 我在 sys.path 上添加了一些评论。

【解决方案3】：

在conf.py

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

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

【讨论】：

路径硬编码并不是你可以用conf.py 做的最好的事情。
如果你有一个像/app、/docs、...这样的项目结构，你可以使用sys.path.append(os.path.join(os.path.dirname(__name__), '..'))，然后在你的.. automodule:: app文件中使用.. automodule:: app。

【解决方案4】：

如果

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

而您的 autodoc 仍然找不到模块...

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

【讨论】：

我不明白为什么 sphinx 需要依赖项，是因为可能在文档字符串中进行测试吗？这可以避免吗（我不需要任何包，我只是想让 sphinx 将 docstring 解析为 html）。
如果您不想导入这些依赖项，请在 conf.py 文件中使用 autodoc_mock_imports：sphinx-doc.org/en/master/usage/extensions/…

【解决方案5】：

我不知道为什么（也许在我的情况下 autodoc 无法安装我的包），但我总是收到 module-not-found 错误，直到我明确地将所有包含模块的目录包含到路径中。

对于以下示例文件夹结构

project_dir
|- setup.py
|- src
|  |- __init__.py
|  |- source1.py
|  |- sub_project
|     |- __init__.py
|     |- source2.py 
|- docs
    |- conf.py
    |- source
    |  |- index.rst
    |- _build

我包括

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

到conf.py 的开头，以便添加所有涉及的目录。

【讨论】：

【解决方案6】：

我想我第一次尝试将文件添加到目录树时就这样做了。我认为这是因为我在 :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 与它位于同一目录中。

【讨论】：

这会去哪里？我在/docs/source 和/ys_utils 中有index.rst。我猜这应该是docs 版本？我只是使用使用sphinx-quickstart 创建的默认index.rst 文件。
-1 从回溯中可以看出模块不在sys.path 中，因此autodoc 找不到它们。找到了.rst 文件。

【解决方案7】：

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

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

.. automethod:: mymodule::func

请参阅autoclass documentation 中的1.3 版中的新功能部分。

【讨论】：

【解决方案8】：

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

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

Pweave 将执行这些块，并将它们替换为生成的 rst 文件中的输出，然后您可以将其与 sphinx 一起使用。有关外观的更多详细信息，请参阅Pweave reST example。

【讨论】：