1

我正在使用 Sphinx 自动文档和拿破仑扩展来为我的项目 ( Qtools ) 生成文档。这在我的本地机器上运行良好。我正在使用 Sphinx 3.1.2（或更高版本）。但是，当我在 Read the Docs (RTD) 上构建文档时，只会处理直接添加到构成文档源的 reStructuredText 文件的文本。应该由 autodoc 提取的文档字符串不会出现在RTD 生成的 HTML 文档中。所以例如在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（将功率谱转换为响应谱）。

换句话说，所有指令显然都被忽略了，并且没有添加到其他函数的超链接。我已经检查了几个基本的指导文件，比如这个，但我不知道我做错了什么。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('../../..')). 这些都没有任何区别。

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

4

1 回答 1

1

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

这有点不正确。正如您在构建日志中看到的，autodoc正在发出许多类似这样的警告：

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

正如您在过去sys.path.insert的一些构建中看到的那样，您的所有变体都发生了这种情况。

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

相反，有两种选择：

  • 找到它所在的conf.py位置（请参阅如何正确确定当前脚本目录？）并从那里计算出一个相关包。
  • 花一些时间使用最新的 Python 打包标准使您的代码可安装，例如将所有源代码放在一个qtools目录中，并pyproject.toml使用flit.
于 2021-08-18T10:15:13.277 回答