ReadTheDocs 不解析 Python 模块中的文档字符串（Sphinx）

Question

我已经开源了我的一些代码，但是文档无法在 ReadTheDocs 上正确构建，尽管使用 sphinx-quickstart 和 make html 在本地创建的 Makefile 按预期工作。谁能告知我在 RTD 集成方面做错了什么？

我已经阅读了有关可能使用 RTD 高级设置在 virtualenv 中构建模块的信息，但这不起作用，因为我有 scipy 作为要求，并且由于没有可用的 BLAS 库而构建失败（这也是一项不必要的长任务对于每个构建的文档）。

sphinx.ext.autodoc 和 sphinx.ext.napoleon（用于谷歌风格的文档字符串）都包括在内。在本地，我只运行了一次dev-scripts/api-docs.sh，它创建了docs/source/bnol.rst 和docs/source/modules.rst。然后使用标准 Makefile（在 git repo 中忽略）按预期构建文档。

• GitHub repository 与 /bnol/ 中的包
• Sphinx conf.py
• RTD-hosted docs not built properly

编辑：我发现了这个FAQ detailing the build process on RTD 并在本地使用了与sphinx-build 相同的过程，它按预期工作。我正在搜索 RTD 日志以查找错误，但目前还没有什么值得注意的。

Answer 1

使用 Sphinx 的 autodoc 从 docstring comments 创建文档需要加载 Python 文件，因此它们导入的所有模块也将被导入。 ReadTheDocs 将构建所需的模块，尤其是在 numpy 和 scipy 的情况下，可能会失败。

我通过从setup.py 中删除模块并将它们列在包根目录中的pip 需求文件./requirements.txt 中来纠正问题，以便在实际包安装中使用。然后将一个虚拟（空）需求文件放置在 ./docs/source/ 中，并将 ReadTheDocs 配置指向那里（即使未指定，它似乎也会自动加载 ./requirements.txt，因此需要虚拟）。

这仍然存在导入模块的问题，该问题已通过mock 修复，如我的./docs/source/conf.py 文件中所见，详细信息见： http://blog.rtwilson.com/how-to-make-your-sphinx-documentation-compile-with-readthedocs-when-youre-using-numpy-and-scipy/

完整的更改列表请参见commit that solved the problem。