python - Python 3.* 中的 Sphinx 和相关导入

Question

我有一个包含 python 包的目录，如下所示:

--docs/index.rst
--docs/...
--app/__init__.py
--app/foo.py

我正在使用 sphinx 和 autodocs 来记录应用程序(在 python 3.3 中)。

现在，在 conf.py(在 docs/ 内)，我有

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

我cd进入docs/，运行

make html

这给了我

SystemError: Parent module '' not loaded, cannot perform relative import

所有有

的模块

from .foo import Bar

我有一个干净的 Sphinx virtualenv 安装使用

pip install Sphinx

在我为 python 3.3 创建(干净的)环境之后。

我错过了什么？

发生这种情况时，我正将项目从 python 2.* 移至 python 3.*。所有项目都在运行，但是这...

Answer 1

您的 app 目录是一个包。包是一个目录，其中包含 __init.py__ 和其他文件。

如果将包目录放在 sys.path 上，就会出现各种问题。

举个例子:

root/
    app/
        app/__init__.py
        app/spam.py
        app/eggs.py

---

如果您的 sys.path 上有 root(因为它是您当前的工作目录，或者因为您明确地这样做了，或者因为您已经正确地安装了一些东西到你的 site-packages), 那么 app 是一个包, app.spam 是一个模块, 在 app.eggs, .spam 就是那个模块。所以，一切正常。

如果您的 sys.path 上有 app，则 app 不是包，spam 是一个模块，在 eggs 中，.spam 什么都不是。因此，您不能使用相对导入。

如果您的 sys.path 上有 both，则 app 是一个包，spam 和 app.spam都是不同的模块(内容相同，执行两次)，在app.eggs中，.spam是一个模块，但是在 eggs 中，.spam 什么都不是。这会给你带来无穷无尽的问题。

---

所以，很可能，您想要的修复是这样的:

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

如果在 .. 中有您不想自动记录的其他包或充满 Python 代码的目录(例如，tests 包含 tests/test_spam.py 的目录)，那么您需要重组目录以将 app 放入某个没有任何其他 Python 代码的目录中，像这样:

root/
    src/
        app/
    tests/
    doc/

---

或者，如果您不希望 app 成为一个包，而是成为一个 sys.path 根目录，则终止 __init__.py，并且将 app 直接留在 sys.path 中。但在那种情况下，您不能使用包内相对导入； app 中的所有模块都是顶级模块，必须按原样导入。

---

Packages本教程的一部分(以及上面一章的其余部分)解释了其中的一些内容，但那里可能有更好的介绍性文档。

有关 3.3+ 的完整详细信息，The import system应有尽有，井井有条；对于旧版本，引用文档是困惑的、不完整的和分散的；你必须从The import statement开始，然后阅读 The Knights Who Say Neeeow ... Wum ... Ping! (它基本上是一个 PEP，但 1.5 还没有 PEP)，甚至可能还有 ni 文档，如果你能找到它，加上各种 PEP 和解释事情如何变化的微小变化日志条目在 1.5 和 2.7 或 3.2 或其他任何值之间。