Sphinx找不到我的python文件。表示“没有名为的模块…”

Question

我有一个关于Sphinx autodoc生成的问题。我觉得我要做的应该很简单，但由于某些原因，它不会起作用

我有一个Python项目，其目录名为slotting\u 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的目录。不知道这是否会引起一些麻烦

有人有主意吗

Answer 1

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 2

当源代码位于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')))

也包括在{}中：

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

在{}中，您可以链接{}：

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 3

让我们以一个项目为例：^{} on master branch，提交：6cbcc2c72d5dc74d2defa56bf63706fd628d9892：

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

和utility package has a utils.py module：

遵循此过程（仅供参考，我正在使用斯芬克斯build 3.1.2）：

1. 在项目下创建docs/目录：

mkdir docs
cd docs

1. 在docs/内启动狮身人面像，只需传递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 享受编写代码的乐趣