Sphinx 找不到我的 python 文件。 说“没有模块命名...”

Question

我有一个关于 Sphinx autodoc generation 的问题。 我觉得我想做的事情应该很简单，但由于某种原因，它行不通。

我有一个 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

现在，我通过将以下内容添加到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:

当尝试使用sphinx-build -b html source.\build命令构建我的 html 时，我得到以下 output， 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的目录。 不知道这样会不会造成什么麻烦？

有人有想法吗？

Answer 1

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

遵循以下步骤：

1. 在您的Project目录中创建一个docs目录（它是从这个docs目录执行以下步骤中的命令）。

2. sphinx-quickstart （从build选择单独的source 。将.html和.rst文件放在不同的文件夹中）。

3. sphinx-apidoc -o ./source ../src

4. 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` 后，结果：

和：

Answer 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 文件可以更轻松地诊断问题并提供相关帮助：推断的越少，可以推断的越少答案是错误的。

Answer 3

让我们以一个项目为例： 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 ）：

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

mkdir docs
cd docs

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

sphinx-quickstart

您将在docs/文件夹中获得以下自动生成的信息

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

因为，我们创建了一个单独的docs目录，所以我们需要 sphinx 找到在哪里可以找到构建文件和 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上托管您的文档，享受记录您的代码的乐趣！

Answer 4

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

$ python setup.py install

Answer 5

恕我直言，运行pip install --no-deps -e. 在顶级项目文件夹（或setup.py所在的位置）中获得“可编辑”安装是在PYTHONPATH上获取 package 模块的更好选择，而不是使用sys.path在docs/conf.py中更改它。