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

Question

我已经开源了一些我的代码，但是文档在ReadTheDocs上无法正确生成，尽管使用由和创建的Makefile可以按预期工作。请问有人能指导我RTD集成出了什么问题吗？

我已经阅读过可能需要在虚拟环境中使用RTD高级设置构建模块，但由于我需要scipy作为要求，而由于没有可用的BLAS库，构建失败（对于每个文档构建来说这也是一个不必要的漫长任务）。 和（用于Google风格的docstrings）都被包含在内。本地上，我只需运行一次，即可创建和。然后使用标准的Makefile（在git repo中被忽略）按预期构建文档。

• GitHub代码仓库，其中包含/bnol/文件夹
• Sphinx conf.py
• RTD托管的文档没有正常构建

编辑：我找到了这个关于在RTD上构建过程的FAQ，并在本地使用sphinx-build进行了相同的处理，结果符合预期。我正在查找RTD日志中的错误，但目前还没有找到任何值得注意的内容。

- Arran Schlosberg

---

嘿@Arran，我不是RTD的专家，但看起来你需要在github存储库的BNoL/docs文件夹中的Makefile。我也无法看到你的github设置，但你还需要启用RTD服务钩子设置。一旦你拥有了这两个东西，它应该就能工作了。 - Brad Baskin

感谢@BradBaskin。请查看以下修复方案。 - Arran Schlosberg

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/。

完整的更改列表可以在解决该问题的提交中查看。

- Arran Schlosberg

---

这帮助我解决了我的问题，但我发现您不必从setup.py中删除模块，只需创建模拟要求文件并将RTD指向它即可。感谢您发布自己问题的解决方案。 - Jared Andrews

我曾经遇到过同样的问题；在我的 repo_dir/docs/conf.py 文件中，我设置了 sys.path.insert(0, os.path.abspath('../app_dir')) 对应于 repo_dir/app_dir/__init__.py。通过将其更改为 sys.path.insert(0, os.path.abspath('../')) 来解决了这个问题。 - user5359531

Answer 2

1. 首先，您需要确保在conf.py中正确加载包路径。请注意错误消息。

   sys.path.insert(0, os.path.abspath('../..')) sys.path.insert(0, os.path.abspath('../ExceptNotifier/init.py'))

2. 如果您正确查看了包路径，请检查requirments.txt中是否正确安装了与shpinx相关的所有包。此外，请记住，每个主题的args和依赖包都不同。

   extensions = [ 'sphinx.ext.autodoc','sphinx.ext.todo' ]

3. Sphinx只验证一次包。集中处理必须编译的错误。

4. 在我的情况下，所有具有相同docstring的模块都未公开。所有docstring都不能相同。如果复制粘贴使dostrings相同，请更改它们。

5. 当文档仅在本地资源中工作时。请检查此stackoverflow:Docstrings are not included in Read the Docs Sphinx build

- danielpark