Sphinx 找不到我的 Python 文件。提示“没有名为...的模块”
- 2025-03-26 09:08:00
- admin 原创
- 18
问题描述：
我对 Sphinx 自动文档生成有疑问。我觉得我尝试做的事情应该非常简单，但不知为何，它不起作用。
我有一个名为的 Python 项目slotting_tool。此目录位于C:UsersSamDesktoppicnic-data-shared-toolsstandaloneslotting_tool
我使用 设置了 Sphinx sphinx-quickstart。我的目录结构（简化）如下：
slotting_tool/
|_ build/
|_ source/
|___ conf.py
|___ index.rst
|_ main/
|___ run_me.py
slotting_tool现在，我通过在文件中添加以下内容来设置项目的根目录conf.py。
import os
import sys
sys.path.insert(0, os.path.abspath('..'))
接下来，我将更新我的index.rst文件，使其如下所示：
.. toctree::
:maxdepth: 2
:caption: Contents:
.. automodule:: main.run_me
:members:
当尝试使用命令构建我的 html 时sphinx-build -b html source .uild，我收到以下输出，并出现no module named错误：
(base) C:UsersSamDesktoppicnic-data-shared-toolsstandaloneslotting_tool>sphinx-build -b html source .uild
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。不知道这是否会造成麻烦？
有人有想法吗？
解决方案 1：
这是“入门”的通常“规范方法”，适用于源代码驻留在目录中而不是简单地位于基目录中的情况。src`Project/src`Project
请遵循以下步骤：
在您的目录中创建一个
docs目录（以下步骤中的命令Project都是从这个目录执行的）。docssphinx-quickstart（选择source与不同文件夹中的build位置.html和文件分开）。.rstsphinx-apidoc -o ./source ../srcmake 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：
让我们以一个项目为例：dl4sci-school-2020在 master 分支上，提交：6cbcc2c72d5dc74d2defa56bf63706fd628d9892：
├── dl4sci-school-2020
│ ├── LICENSE
│ ├── README.md
│ ├── src
│ │ └── __init__.py
│ └── utility
│ ├── __init__.py
│ └── utils.py
实用程序包有一个 utils.py 模块：
遵循这个过程（仅供参考，我正在使用sphinx-build 3.1.2）：
在你的项目下创建一个
docs/目录：
mkdir docs
cd docs
在内启动sphinx
docs/，只需传递你的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://i.sstatic.net/5pvLu.jpg
仅供参考，您可以切换您选择的任何主题，我发现sphinx_rtd_theme一个扩展sphinxcontrib.napoleon非常棒！感谢它们的创造者，所以我使用了它。
下面做工作！
pip install sphinxcontrib-napoleon
pip install sphinx-rtd-theme
您可以在readthedocs上托管您的文档，
享受记录您的代码的乐趣！
解决方案 3：
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 文件可以更轻松地诊断问题并提供相关帮助：推断的越少，答案的错误就越少。
解决方案 4：
pip install --no-deps -e .我认为，在顶级项目文件夹（或任何地方）运行setup.py以获取“可编辑”安装是获取包模块的更好选择，而不是在使用PYTHONPATH中对其进行更改。docs/conf.py`sys.path`
