Sphinx 构建失败-autodoc 无法导入/查找模块

小开

我想我在第一次尝试向 toctree 添加文件时做到了这一点。我认为这是因为我在: maxdeep 行和文件名之间省略了空行。

.. 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 与它位于同一目录中。

小开

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

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

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

make

看看有什么选择。

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

make clean

在运行 make html之前。

小开

在 conf.py

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

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

小开

您可以使用转圈和 noweb 格式化来生成包含嵌入其中的代码输出的 rst 文档。基本上，编写第一个文件时，将 Python 代码嵌入到标记的块中，如下所示:

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

Pweave 将执行这些块，并将它们替换为生成的 rst 文件中的输出，然后您可以使用 sphinx。请参阅编写 reST 示例了解更多关于它看起来如何的细节。

小开

解决方案

听起来 os.path.append()对于大家来说是可行的，但是如果您遵循 conf.py模板，那么您将使用 os.path.insert(0, ...)插入到 sys.path前面的模块路径，并且只添加一个额外的 .

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变量来完成的(参见关于模块搜索路径模块搜索路径的文档)。

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

.-conf.py的当前路径

..-conf.py的父路径

../..-父路径的父路径，等等。

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

from pathlib import Path


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

小开

我得到了同样的错误，但它是由一个完全不同的原因，而不是解释在其他的答案。

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

.. automethod:: mymodule::func

请参阅 autoclass文档中的 版本1.3中新增部分。

小开

如果

在 conp.py 中正确设置了模块根路径
__init__.py放置正确
Rst 语法正确

你的自动博士还是找不到模块。

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

小开

我不知道为什么(也许在我的情况下 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的开头，这样所有涉及的目录将被添加。

小开

本文从正确的方向讨论了线程中的许多解决方案。对我来说，官方文件上的命令很有帮助。

import pathlib
import sys
sys.path.insert(0, pathlib.Path(__file__).parents[2].resolve().as_posix())

小开

我在文件 conf.py的开头添加以下一行:

import os
import sys
sys.path.insert(0, os.path.abspath('..'))
sys.path.append(os.path.abspath(
os.path.join(__file__, "../../src")
))

我的项目有下一个结构:

project_dir
|- setup.py
|- src
|  |- __init__.py
|  |- ....
|- docs
|- conf.py
|- ...