尝试在Sphinx-DOC上进行相对导入时出错

问题描述

我尝试使用Sphinx-DOC的自动文档功能。我想解决以下问题。当时，StackOverflow的解决方案都没有奏效。 是由于我的项目结构还是我选择导入模块的方式？

给定的文件结构：

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

以下配置系统路径：

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

---

解决方案

将项目根目录而不是源目录添加到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
 │             └── ...

另一个使用单一目录存储Shinx文档的示例。

#  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