【问题标题】：Docstrings are not generated on Read the Docs with Sphinx autodoc and napoleon extensions使用 Sphinx autodoc 和拿破仑扩展阅读文档时不会生成文档字符串
【发布时间】：2021-08-17 08:38:47
【问题描述】：

我正在使用 Sphinx 自动文档和拿破仑扩展来为我的项目 (Qtools) 生成文档。这在我的本地机器上运行良好。我正在使用 Sphinx 3.1.2（或更高版本）。但是，当我在 Read the Docs (RTD) 上构建文档时，只会处理直接添加到构成文档源的 reStructuredText 文件的文本。应该由 autodoc 拉入的文档字符串不会出现在 the HTML documentation generated by RTD 中。所以例如在docs\source\section2_rsdoc.rst 我有：

Response spectra
================

The response spectrum class
---------------------------

.. autoclass:: qtools.ResponseSpectrum
   :members:

Response spectrum creation
--------------------------

.. autofunction:: qtools.calcrs

.. autofunction:: qtools.calcrs_cmp

.. autofunction:: qtools.loadrs

See also :func:`qtools.convert2rs` (converts a power spectrum into a response spectrum).

这会导致：

反应谱

反应谱类

反应谱创建

另见qtools.convert2rs（将功率谱转换为响应谱）。

换句话说，所有指令显然都被忽略了，并且没有添加到其他函数的超链接。我检查了几个基本的指导文件，例如this one，但我无法弄清楚我做错了什么。 RTD 构建文档时没有任何错误或警告。在 RTD 高级设置中，我有：

文档类型：Sphinx HTML
需求文件：requirements.txt
Python 解释器：CPython 3.x
安装项目：否
使用系统包：否
Python 配置文件：空白
启用 PDF 构建：否
启用 EPUB 构建：否

我没有碰任何其他设置。

在conf.py 中，我尝试了第 15 行的以下变体：sys.path.insert(0, os.path.abspath('.'))、sys.path.insert(0, os.path.abspath('../..')) 和当前的sys.path.insert(0, os.path.abspath('../../..'))。这些都没有任何区别。

如果有任何帮助，我将不胜感激！

【问题讨论】：

标签： read-the-docs autodoc sphinx-napoleon

【解决方案1】：

RTD 构建文档时没有任何错误或警告

这有点不正确。正如您在the build logs 中看到的那样，autodoc 正在发出许多类似这样的警告：

WARNING: autodoc: failed to import class 'ResponseSpectrum' from module 'qtools'; the following exception was raised:
No module named 'qtools'

sys.path.insert 的所有变体都发生了这种情况，您可以在 some past builds 中看到。

试图让它以这种方式工作是很棘手的，因为 Read the Docs 可以猜测文档所在的目录以及工作目录在命令之间的变化。

相反，有两种选择：

找到conf.py所在的位置（参见How do you properly determine the current script directory?）并从那里制定一个相关的包。
花点时间让您的代码可以使用最新的 Python 打包标准进行安装，例如将所有源代码放在 qtools 目录中，并使用 flit 创建适当的 pyproject.toml 文件。

【讨论】：