如何设置 Read the Docs 以便 Sphinx 自动文档选项起作用？

Posted 2023-03-30

【中文标题】如何设置 Read the Docs 以便 Sphinx 自动文档选项起作用？

【英文标题】：How can I set up Read the Docs so the Sphinx autodoc option works?

【发布时间】：2014-02-16 13:05:41

【问题描述】：

我的项目不是使用 autodoc 构建的。我遇到了this frequently asked question about my project not building in autodoc。但是，一些依赖项包括不会在 Build Docs 服务器上执行的 c 代码。所以我阅读了这个blog explaining that I should use mock 中的方法。这与 *** 问题“how-to-mock-so-that-from-x-import-works”有关。

在 Read the Docs 的管理页面的高级设置部分，有一个使用 virtualenv 的选项，我检查了它，然后请求了我的项目根目录到 requirements.txt 的路径。

项目目录结构如下：

GatherNews/
    requirements.txt

当我使用GatherNews/requirements.txt 作为路径时。我得到了错误：

/var/build/user_builds/gathernews/checkouts/latest/docs/api/grss.rst:10：警告：autodoc：无法从模块 u'gathernews.gRSS' 导入类 u'CaptureFeeds'；引发了以下异常：

Traceback（最近一次调用最后一次）：

文件“/home/docs/checkouts/readthedocs.org/user_builds/gathernews/envs/latest/local/lib/python2.7/site-packages/sphinx/ext/autodoc.py”，第 335 行，在 import_object 导入(self.modname)

文件“/home/docs/checkouts/readthedocs.org/user_builds/gathernews/envs/latest/local/lib/python2.7/site-packages/gathernews/init.py”，第 1 行，在导入 gRSS 中

文件“/home/docs/checkouts/readthedocs.org/user_builds/gathernews/envs/latest/local/lib/python2.7/site-packages/gathernews/gRSS.py”，第 38 行，导入 feedparser

ImportError: No module named feedparser /var/build/user_builds/gathernews/checkouts/latest/docs/_themes/README.rst:: WARNING: document is not included in any toctree

我的问题是如何将这一切联系在一起？具体来说，我是否使用我的requirements.txt 的正确路径来阅读文档以成功构建？如果我的requirements.txt 的路径是正确的，那么如何包含模拟包以成功生成自动文档？

【问题讨论】：

就目前而言，这个问题很难回答，因为没有简单的方法来测试任何潜在的答案。如果你能提供一个关于你的项目是如何设置的简约框架，以及你已经尝试过什么以及它是如何失败的，那么它可能有更好的机会得到回答。

我添加了一些我认为会有所帮助的内容，谢谢。

您可以像这样检查requirements.txt 的路径是否正确：包括对requests 模块的依赖，尽早在项目中导入它（***__init__.py） ，在本地构建文档没有满足依赖关系以检查这是 Sphinx 引发的第一个错误，然后让 RTD 构建它。

我已经能够在本地使用 sphinx 构建文档并且一切看起来都不错。这只是阅读文档的自动文档问题。让我提供更多信息，希望能更好地解释我自己。

【参考方案1】：

我创建了一个 https://github.com/Bonza-Times/GatherNews 的分支并为其创建了一组 ReadTheDocs。唯一的问题似乎是您使用了错误的路径到requirements.txt。它说

项目根目录的路径。

所以不包括GatherNews。只需使用 requirements.txt 作为路径，因为该文件位于 git 存储库的顶层。

由于您已选中 Use virtualenv，ReadTheDocs 应自动确保 virtualenv 的站点包在 sys.path 中对 sphinx-build 脚本可用。

我认为不需要模拟模块，因为feedparser 对 C 库没有任何硬依赖。它可以针对 libxml2 构建，但不是必须的。

修复了requirements.txt 的路径后，我能够成功构建。

这些是我使用的“高级设置”，其余设置为默认值：