Sphinx-doc 上的错误“尝试相对导入”

Question

我尝试使用 Sphinx-doc 的自动文档。我想解决以下问题。目前，StackOverflow 没有任何解决方案有效。 是因为我的项目结构还是我选择导入模块的方式？

给定文件结构：

project
 |_ src
 |   |_ pre_processing
 |   |     |_ fileInfo.py
 |   |
 |   |_ utils
 |         |_ folder.py
 |_ test
 |      
 |_ doc
 |   |_ doc_user
 |        |_ build
 |        |_ source
 |             |_config.py

以下配置 sys.path ：

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

我在 fileInfo.py 中有一些相对导入：

from ..utils.folder import get_files_directory

终端错误

WARNING: autodoc: failed to import module 'pre_processing.fileInfo'; the following exception was raised:
Traceback (most recent call last):

File "/home/florian-stage/miniconda/envs/gd/lib/python3.5/site-packages/sphinx/ext/autodoc/importer.py", line 140, in import_module
__import__(modname)

File "/home/florian-stage/Projet-2018/pg_georef_data-master/arbo propre/src/pre_processing/fileInfo.py", line 12, in <module>
from ..utils.folder import get_files_directory
ValueError: attempted relative import beyond top-level package

Answer 1

您的问题似乎与您的项目结构有关。正如CristiFati 建议的那样，您的每个文件夹中都应该有__init__.py 文件，包括project。 The docs on packages 认为这是必要的：

init.py 文件是 Python 将目录视为包含包所必需的；这样做是为了防止具有通用名称（例如字符串）的目录无意中隐藏模块搜索路径中稍后出现的有效模块。

为了测试您的代码，您需要从某个 main.py 文件运行，因为导入将相对于顶级文件夹（在本例中为 project）。以下是文件结构的外观：

project
 |  __init__.py
 |  main.py
 |_ src
 |   |  __init__.py
 |   |_ pre_processing
 |   |     |  __init__.py
 |   |     |  fileInfo.py
 |   |
 |   |_ utils
 |         |  __init__.py
 |         |  folder.py
 |_ test
 |   |  __init__.py
 |      
 |_ doc
 |   |  __init__.py
 |   |_ doc_user
 |        |  __init__.py
 |        |_ build
 |             |  __init__.py
 |        |_ source
 |             |  __init__.py
 |             |  config.py

那么在main.py 你应该有：

from src.pre_processing import fileInfo

运行 main.py 现在应该会产生无错误的输出。

Answer 2

我知道这是一个老问题，但是，你能解决它吗？

如果有人对 Sphinx 和相关导入也有问题，我建议试试这个（按照这个问题的初始示例）：

1. 在 config.py 中替换：

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

与

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

1. 如果您使用自动文档，则必须更改 .rst 文件，例如：

.. automodule:: pre_processing.fileInfo

与：

.. automodule:: src.pre_processing.fileInfo

注意：没有必要创建 __init__.py 文件，正如我在之前的答案中看到的那样。

问候。

Answer 3

将项目根目录而不是源目录添加到 sys.path 似乎可以解决问题。请记住添加__init__.py 文件来声明包。

之后，您还应该在 *.rst 文件中修改对模块的引用，在 src 前面添加。

示例：

#  in "doc/doc_user/source/config.py"
import os
# ("../../..") instead of ("../../../src")!
sys.path.insert(0, os.path.abspath("../../.."))

__init__.py中的示例定义

#  in "src/utils/__init__.py"
from .folder import get_files_directory

在文件信息中导入。可能会有所不同，具体取决于您将get_files_directory 导入__init__.py 的方式或是否完全导入。

# in "src/pre_processing/fileInfo.py"
from ..utils import get_files_directory

任何*.rst 文件中的引用应如下所示。 （前置src）

.. automodule:: src.pre_processing.fileInfo
  :members:

project
 ├── src
 │   ├── __init__.py
 │   ├── ...
 │   ├── pre_processing
 │        ├── __init__.py
 │        ├── fileInfo.py
 │   └── utils
 │        ├── __init__.py
 │        └── folder.py
 ├── test
 ├── doc
 │   └── doc_user
 │        ├── build
 │        └── source
 │             ├── config.py
 │             └── ...

另一个使用单个目录保存 sphinx 文档的示例。

#  in "docs/conf.py"
import os
# ("..") instead of ("../src")!
sys.path.insert(0, os.path.abspath(".."))

project
 ├── src
 ├── test
 ├── docs
 │    ├── _static
 │    ├── _templates
 │    ├── ...
 │    ├── index.rst
 │    └── conf.py
 ├── ...
 ├── setup.cfg
 └── setup.py

参考文献

1. The import system
2. Python Modules and Packages – An Introduction
3. Implicit Namespace Packages