Sphinx自动文档生成工具无法导入模块

Question

我正试图使用Sphinx来记录一个项目，但遇到了一个问题：只有一些模块从文件夹中被导入。我的项目结构如下所示：

Project
|
|--Main
|    |--Scripts
|          __init__.py
|          libsmop.py
|          conv_table.py
|          f_discrim.py
|          recipes.py
|          ...

当我尝试运行make html时，libsmop和recipes被成功导入，但是conv_table和f_discrim出现了以下错误: WARNING: autodoc: failed to import module u'conv_table' from module u'Scripts'; the following exception was raised:No module named conv_table 我认为这不是我的配置文件的问题，因为当我运行sphinx-apidoc -o _rst Main/Scripts时，它可以找到所有的文件，并且我已经确认它们出现在生成的Scripts.rst文件中。

为什么autodoc能够找到某些模块却找不到其他的模块呢？

编辑： conv_table.py的格式如下：

import re
import numpy as np

"""
conv_table dictionary at the bottom of this file maps from matlab functions
to their python equivalents.
"""

def get_args(line,separator=",", open_char='(', close_char=')'):
    """Returns the arguments of line

    >>> get_args('ones(3,1,length(arr))')

...
< a bunch of function definitions>
...

conv_table = {... < a very big dictionary > ...}

- Alex Cavanaugh

---

有 __init__.py 文件吗？每个目录都需要它来使它成为 Python 模块并可导入。 - Steve Piercy

是的，我在“Scripts”目录中有一个“init.py”文件。 - Alex Cavanaugh

Sphinx的autodoc命令长什么样？ - user9903

Answer 1

由于您的自动文档捕获了一些模块，这可能是因为失败的模块的依赖项未正确导入或未安装在您的Python环境下。您需要检查所有导入语句是否在失败的模块中起作用。

- Ingako

---

太棒了！我猜 Sphinx 不应该吞掉 Python 解释器中的警告。 - Colin

Answer 2

你需要检查模块加载路径，根据Sphinx文档的说明：

要让Sphinx（实际上是执行Sphinx的Python解释器）找到你的模块，它必须是可导入的。这意味着模块或包必须位于sys.path上的一个目录中-请在配置文件中相应地调整sys.path。

另外，了解一下Scripts目录中的__init__.py和conv_table模块的内容也会很有用。

- user9903

---

我认为模块加载路径是正确的，因为它正在获取文件夹中的一些模块。我现在会添加一个编辑，显示我的conv_table，但是我的__init__.py只包含注释。 - Alex Cavanaugh

同时在你的 conf.py 中添加任何定义 sys.path 的行。 - Steve Piercy

我有两行代码可以实现这个功能： sys.path.insert(0, os.path.abspath('.')) sys.path.append('Main') - Alex Cavanaugh

@AlexCavanaugh 这个代码是开源的吗？没有其他源代码很难看出路径上发生了什么。 - user9903

不幸的是它不是开源的。但是我认为我应该可以做出类似 sys.path.append(os.path.abspath('./Main/Scripts')) 这样的事情，因为 Sphinx 是在 Project 目录下运行的。这听起来对吗？ - Alex Cavanaugh

Answer 3

我曾经遇到过类似的问题，解决方法是在../source/conf.py文件中添加包含该模块的路径：

sys.path.insert(0, os.path.abspath('相对于您的文件夹结构有效的任何相对路径')) sys.path.append('/path/to/the/conv_table/')

- Maher Nouredline

Answer 4

在您的环境中安装此库应该解决目前的问题：

pip install sphinxcontrib-bibtex

在运行make html命令后，可能会警告您有关配置问题的信息。

- Waqar Ahmad

---

奇怪的回答。问题中没有任何东西表明安装sphinxcontrib-bibtex会解决问题。 - mzjn

哈哈，我知道这个，我的评论并不意味着我认为它会解决你的问题，但对于像我一样寻找潜在解决方案的其他人来说，可能会有帮助。至于它是否能够解决问题，我也曾有同样的想法，但出乎意料地它对我起了作用，我也没有费心去调试原因，你可以尝试看看它是否适用于你。 - Waqar Ahmad