狮身人面像自动文档/拿破仑不生成文档字符串

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

我使用的是斯芬克斯4.0.2版本。我安装了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。我在index.rst中的toctree中添加了"模块"，"模拟器"在modules.rst中自动构建的toctree中。

它在每个文件中创建一个标题和一个toctree。没有文档字符串。我读到它只是创建了一个模型来从文档字符串构建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'))