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

Question

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

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

我使用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:

尝试使用该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. 不知道这样会不会造成什么麻烦？

有人有想法吗？

Answer 1

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

遵循以下步骤：

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

2. sphinx-quickstart（选择独立source的build。地方.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 步之后）：

Project
|
????docs
?   ?   make.bat
?   ?   Makefile
?   ?
?   ????build
?   ????source
?       ?   conf.py
?       ?   index.rst
?       ?   modules.rst
?       ?   stack.rst
?       ?
?       ????_static
?       ????_templates
????src
        stack.py

还包括在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

让我们以一个项目为例：dl4sci-school-2020在 master 分支上，提交： 6cbcc2c72d5dc74d2defa56bf63706fd628d9892：

\n

\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 dl4sci-school-2020\n\xe2\x94\x82\xc2\xa0\xc2\xa0 \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 LICENSE\n\xe2\x94\x82\xc2\xa0\xc2\xa0 \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 README.md\n\xe2\x94\x82\xc2\xa0\xc2\xa0 \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 src\n\xe2\x94\x82\xc2\xa0\xc2\xa0 \xe2\x94\x82\xc2\xa0\xc2\xa0 \xe2\x94\x94\xe2\x94\x80\xe2\x94\x80 __init__.py\n\xe2\x94\x82\xc2\xa0\xc2\xa0 \xe2\x94\x94\xe2\x94\x80\xe2\x94\x80 utility\n\xe2\x94\x82\xc2\xa0\xc2\xa0     \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 __init__.py\n\xe2\x94\x82\xc2\xa0\xc2\xa0     \xe2\x94\x94\xe2\x94\x80\xe2\x94\x80 utils.py\n

\n

实用程序包有一个 utils.py 模块：

\n

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

\n

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

\n

mkdir docs\ncd docs\n

\n

\n
2. 在 内启动 sphinx docs/，然后传递您选择的project_name, your_name& version，其余保留默认值。
\n

\n

sphinx-quickstart\n

\n

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

\n

\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 docs\n\xe2\x94\x82\xc2\xa0\xc2\xa0 \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 Makefile\n\xe2\x94\x82\xc2\xa0\xc2\xa0 \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 build\n\xe2\x94\x82\xc2\xa0\xc2\xa0 \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 make.bat\n\xe2\x94\x82\xc2\xa0\xc2\xa0 \xe2\x94\x94\xe2\x94\x80\xe2\x94\x80 source\n\xe2\x94\x82\xc2\xa0\xc2\xa0     \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 _static\n\xe2\x94\x82\xc2\xa0\xc2\xa0     \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 _templates\n\xe2\x94\x82\xc2\xa0\xc2\xa0     \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 conf.py\n\xe2\x94\x82\xc2\xa0\xc2\xa0     \xe2\x94\x94\xe2\x94\x80\xe2\x94\x80 index.rst\n

\n

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

\n

import os\nimport sys\nbasedir = os.path.abspath(os.path.join(os.path.dirname(__file__), \'..\', \'..\'))\nsys.path.insert(0, basedir)\n

\n

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

\n

.. toctree::\n   :maxdepth: 2\n   :caption: Description of my CodeBase:\n\n   modules\n

\n

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

\n

sphinx-apidoc -o ./source ..\n

\n

您得到的输出：

\n

\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 docs\n\xe2\x94\x82\xc2\xa0\xc2\xa0 \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 Makefile\n\xe2\x94\x82\xc2\xa0\xc2\xa0 \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 build\n\xe2\x94\x82\xc2\xa0\xc2\xa0 \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 make.bat\n\xe2\x94\x82\xc2\xa0\xc2\xa0 \xe2\x94\x94\xe2\x94\x80\xe2\x94\x80 source\n\xe2\x94\x82\xc2\xa0\xc2\xa0     \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 _static\n\xe2\x94\x82\xc2\xa0\xc2\xa0     \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 _templates\n\xe2\x94\x82\xc2\xa0\xc2\xa0     \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 conf.py\n\xe2\x94\x82\xc2\xa0\xc2\xa0     \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 index.rst\n\xe2\x94\x82\xc2\xa0\xc2\xa0     \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 modules.rst\n\xe2\x94\x82\xc2\xa0\xc2\xa0     \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 src.rst\n\xe2\x94\x82\xc2\xa0\xc2\xa0     \xe2\x94\x94\xe2\x94\x80\xe2\x94\x80 utility.rst\n

\n

现在运行：

\n

make html\n

\n

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

\n

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

\n

你准备好漂亮的文档了吗\n

\n

https://i.stack.imgur.com/5pvLu.jpg

\n

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

\n

下面的工作！

\n

pip install sphinxcontrib-napoleon\npip install sphinx-rtd-theme\n

\n

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

\n

Answer 3

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

这是不正确的。Steve Piercy 的评论并不完全正确（您不需要添加 a，__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 文件使得诊断问题和提供相关帮助变得更加容易：必须推断的越少，可以推断的就越少答案有误。