Sphinx 找不到我的 python 文件。说'没有名为...的模块'答案

【问题标题】：Sphinx cannot find my python files. Says 'no module named ...'Sphinx 找不到我的 python 文件。说'没有名为...的模块'
【发布时间】：2018-12-07 10:52:26
【问题描述】：

我有一个关于 Sphinx 自动文档生成的问题。我觉得我想做的事情应该很简单，但由于某种原因，它不起作用。

我有一个 Python 项目，其目录名为 slotting_tool。该目录位于C:\Users\Sam\Desktop\picnic-data-shared-tools\standalone\slotting_tool

我使用 sphinx-quickstart 设置了 Sphinx。那么我的目录结构（简化）如下：

slotting_tool/
|_ build/
|_ source/
|___ conf.py
|___ index.rst
|_ main/
|___ run_me.py

现在，我通过将以下内容添加到conf.py 文件中，将我的项目的根目录设置为slotting_tool。

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

接下来，我将我的index.rst 文件更新为如下所示：

.. toctree::
   :maxdepth: 2
   :caption: Contents:

.. automodule:: main.run_me
   :members:

当尝试使用sphinx-build -b html source .\build 命令构建我的html 时，我得到以下输出，带有no module named 错误：

(base) C:\Users\Sam\Desktop\picnic-data-shared-tools\standalone\slotting_tool>sphinx-build -b html source .\build
Running Sphinx v1.8.1
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: [] 0 added, 1 changed, 0 removed
reading sources... [100%] index
WARNING: autodoc: failed to import module 'run_me' from module 'main'; the following exception was raised:
No module named 'standalone'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 1 warning.

The HTML pages are in build.

构建中没有引用 run_me.py 的 HTML 页面。我尝试将我的根目录设置为所有不同类型的目录，并尝试将所有点 . 替换为反斜杠 \ 等等，但似乎无法找出我做错了什么。

顺便说一句，standalone 不是模块的说法实际上是正确的，它只是一个没有__init__.py 的目录。不知道会不会有什么麻烦？

有人有想法吗？

【问题讨论】：

我认为你的直觉是正确的。添加一个空的 init.py 并查看导入警告是否消失。
我尝试添加了__init__.py，但这也不能解决错误。您知道其他可能导致此错误的原因吗？
没有看到您的代码，我假设 run_me.py 尝试独立导入但失败。我需要查看代码。
Sphinx 将尝试导入您的所有代码，就像在 Python 解释器中运行它一样。修复您的导入或在 conf.py 中使用 sys 指定不可导入代码的路径。
您的模块必须位于 Sphinx 可以导入的 Python 包中。您需要将该模块与一个空的 __init__.py 文件一起放在一个文件夹中（从而使其成为 Python 包），并在您的 conf.py 中配置该路径，以便 Sphinx 可以导入它。

标签： python python-3.x python-sphinx autodoc

【解决方案1】：

这是“开始”的常用“规范方法”，适用于源代码位于Project/src 等src 目录而不是简单地位于Project 基本目录中的情况。

遵循以下步骤：

在您的Project 目录中创建一个docs 目录（它就是从这个docs 目录执行以下步骤中的命令）。
sphinx-quickstart（从build 中选择单独的source。将.html 和.rst 文件放在不同的文件夹中）。
sphinx-apidoc -o ./source ../src
make html

这将产生以下结构（假设您的 .py 源文件位于 Project/src 中）：

Project
|
├───docs
│   │   make.bat
│   │   Makefile
│   │
│   ├───build
│   └───source
│       │   conf.py
│       │   index.rst
│       │   modules.rst
│       │   stack.rst
│       │
│       ├───_static
│       └───_templates
└───src
        stack.py

在您的conf.py 中添加（在第 2 步之后）：

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

也包括在conf.py:

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']

在index.rst 中，您将链接modules.rst：

Welcome to Project's documentation!
================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   modules
      
   
Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

您的stack.rst 和modules.rst 由sphinx-apidoc 自动生成，无需更改它们（此时）。但只是为了让你知道它们是这样的：

stack.rst:

stack module
============

.. automodule:: stack
   :members:
   :undoc-members:
   :show-inheritance:

modules.rst:

src
===

.. toctree::
   :maxdepth: 4

   stack

`make html` 在浏览器中打开 `Project/docs/build/index.html` 后，结果：

和：

【讨论】：

【解决方案2】：

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

这是不正确的。 Steve Piercy 的评论并不完全正确（您不需要添加__init__.py，因为您使用的是一个简单的模块）但他们是对的，autodoc 将尝试导入模块然后检查内容。

假设你的树是

doc/conf.py
src/stack.py

那么您只是将包含您的存储库的文件夹添加到 sys.path 中，这完全没用。您需要做的是将src 文件夹添加到 sys.path，这样当 sphinx 尝试导入 stack 时，它会找到您的模块。所以你的行应该是：

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

（路径应该相对于 conf.py）。

注意：由于您拥有完全合成且不应包含任何秘密的东西，因此可访问的存储库或整个事物的 zip 文件使诊断问题和提供相关帮助变得更加容易：必须推断的越少，答案越少越好。

【讨论】：

【解决方案3】：

我们以一个项目为例：dl4sci-school-2020 on master branch，commit: 6cbcc2c72d5dc74d2defa56bf63706fd628d9892：

├── dl4sci-school-2020
│   ├── LICENSE
│   ├── README.md
│   ├── src
│   │   └── __init__.py
│   └── utility
│       ├── __init__.py
│       └── utils.py

和utility package has a utils.py module:

遵循这个过程（仅供参考，我正在使用 sphinx-build 3.1.2）：

在您的项目下创建一个docs/ 目录：

mkdir docs
cd docs

在 docs/ 中启动 sphinx，然后传递您选择的 project_name、your_name 和 version，其余保持默认值。

sphinx-quickstart

您将在docs/ 文件夹中自动生成以下内容

├── docs
│   ├── Makefile
│   ├── build
│   ├── make.bat
│   └── source
│       ├── _static
│       ├── _templates
│       ├── conf.py
│       └── index.rst

因为，我们创建了一个单独的 docs 目录，所以我们需要 sphinx find 在哪里可以找到构建文件和 python src 模块。所以，编辑 conf.py 文件，你也可以使用我的 conf.py 文件

import os
import sys
basedir = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..'))
sys.path.insert(0, basedir)

现在，要启用对嵌套的多个包和模块（如果有）的访问，您需要编辑 index.rst 文件。

.. toctree::
   :maxdepth: 2
   :caption: Description of my CodeBase:

   modules

modules 从modules.rst 文件中获取内容，我们将在下面创建该文件：确保您仍在doc/ 中运行以下命令

sphinx-apidoc -o ./source ..

你得到的输出：

├── docs
│   ├── Makefile
│   ├── build
│   ├── make.bat
│   └── source
│       ├── _static
│       ├── _templates
│       ├── conf.py
│       ├── index.rst
│       ├── modules.rst
│       ├── src.rst
│       └── utility.rst

现在运行：

make html

现在，在您选择的浏览器中打开，

file:///<absolute_path_to_your_project>/dl4sci-school-2020/docs/build/html/index.html

你准备好漂亮的文档了吗

https://imgur.com/5t1uguh

仅供参考，您可以切换您选择的任何主题，我发现 sphinx_rtd_theme 和扩展名 sphinxcontrib.napoleon 超级涂料！感谢他们的创造者，所以我使用了它。

下面的工作！

pip install sphinxcontrib-napoleon
pip install sphinx-rtd-theme

您可以在readthedocs 上托管您的文档享受记录您的代码的乐趣！

【讨论】：

【解决方案4】：

对我来说，通过setup.py 文件安装包并重新运行相应的命令解决了这个问题：

$ python setup.py install

【讨论】：