Sphinx autodoc/napoleon 不生成文档字符串

Question

我正在做一个非常简单的示例，但无法使其正常工作。 我只有一个文件， simulator.py ，我在其中添加了 numpy 样式的文档字符串。 它不导入任何其他库。 它有一个__init__ ，我可以从 python 解释器中导入它。 我的目录结构如下：

|__ modules
   |__ __init__.py
   |__ simulator
   |   |__ simulator.py
   |__ docs
       |__ Makefile
       |__ _static
       |__ conf.py
       |__ index.rst
       |__ modules.rst
       |__ _build
       |__ _templates
       |__ simulator.rst
       |__ make.bat

我正在使用 sphinx-build 4.0.2。 我 pip 安装了 sphinxcontrib-napoleon，即使 sphinx-ext.napoleon 应该包含在 sphinx 的更高版本中。

在我的 conf.py 中，我有

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

和

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

为了制作我的.rst文件，我运行sphinx-apidoc -f --ext-autodoc -o. ../simulator sphinx-apidoc -f --ext-autodoc -o. ../simulator来自docs目录。 它创建modules.rst和simulator.rst 。 我在index.rst的目录树中添加了“模块”，而“模拟器”在modules.rst自动构建的目录树中。

它在每个文件中创建一个标题和一个目录树。 没有文档字符串。 我读到它只是创建 model 来从文档字符串构建 html ，所以我运行了make html 。 它仅使用目录构建，文档字符串中没有任何内容。 可能出了什么问题？ 我已经尝试了path.insert()命令的不同变体，即使我很确定我所拥有的是正确的。 我已经尝试将simulator.py移动到主目录中，我尝试从我通过搜索其他解决方案找到的conf.py文件中添加一堆其他随机废话。 没有一个解决方案奏效。

Answer 1

我认为问题来自sys.path.insert(0, os.path.abspath('..')) 。 您实际上是在将modules添加到 Python 路径中，因此import simulator将导入modules/simulator而不是modules/simulator/simulator如您所愿。 你应该这样做：

|__ modules
   |__ simulator
   |   |__ __init__.py
   |   |__ simulator.py
   |__ docs
       |__ ...

并将您的conf.py更改为：

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