如何配置阅读文档以使用 sphinx-autodoc-annotation？答案

【问题标题】：How do I configure Read the Docs to use sphinx-autodoc-annotation?如何配置阅读文档以使用 sphinx-autodoc-annotation？
【发布时间】：2016-08-28 03:29:27
【问题描述】：

我正在使用sphinx-autodoc-annotation 来读取我的 Python 代码中的函数注释，并使用它来生成适当的预期参数类型和返回类型。它在我的本地机器上运行良好，但我当然必须pip install sphinx-autodoc-annotation。

我正在尝试使用Read the Docs 生成相同的文档，但它给了我一个错误：

Could not import extension sphinx_autodoc_annotation (exception: No module named sphinx_autodoc_annotation)

是否可以将 Read the Docs 配置为使用 sphinx-autodoc-annotation，如果可以，我该如何使其工作？

【问题讨论】：

标签： python python-sphinx read-the-docs

【解决方案1】：

我不喜欢通过setup.py 打包一堆文档要求，因此我的建议是不要在 RTD 上使用 Install Project 选项。相反，我更喜欢在我的 doc/ 文件夹中放置一个自定义 requirements.txt，并将 RTD 指向它：

将setup.py 的install_requires 和/或requirements.txt 中的任何内容粘贴到此文件中。确保您正在使用的任何其他 sphinx 扩展也在其中。

这应该照顾你所有的依赖。我推荐的其他有趣设置如下所示：

【讨论】：

【解决方案2】：

为您的 Read the Docs 项目激活 Install Project 选项。

如果激活该选项，Read the Docs 将尝试在您的包上执行setup.py install（请参阅：RtD docs）。在setup.py 中，您可以安装requirements file 中指定的软件包。以source code of the Flask-MongoRest project 为例。

将sphinx-autodoc-annotation 作为唯一要求添加到您的requirements.txt 文件中。

【讨论】：

这很接近，但还没有完全正常工作。我将requirements.txt 添加到docs 文件夹中（因为它只需要构建文档，而不是项目本身），在RtD 设置中指出，打开“使用setup.py install 在virtualenv 中安装你的项目” .我没有收到错误，但现在无法创建 py-modindex.html 文件，该文件是我在本地运行 Sphinx 时创建的。我认为我需要发布带有所有这些额外细节的问题。