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 文件，我从 docs 目录中运行 sphinx-apidoc -f --ext-autodoc -o . ../simulator。它创建 modules.rst 和 simulator.rst。我将 'modules' 添加到 index.rst 中的 toctree，并且 'simulator' 在 modules.rst.

中自动构建的 toctree 中

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

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'))

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

Sphinx autodoc/napoleon doesn't generate docstrings

python

python-sphinx

autodoc

sphinx-napoleon