阅读文档集成

与ReadtheDocs集成

注册阅读文档

注册阅读文档帐户：

https://readthedocs.org/

在“读取文档”中创建集成

进入“管理”->“集成”，单击“添加集成”

_images/rtd_integrations_1.png

选择集成类型为“Github Incoming Webhook”，然后单击“添加集成”

_images/rtd_integrations_2.png

将Webhook URL复制到剪贴板

_images/rtd_integrations_3.png

在GitHub上设置服务

进入Github上项目的管理页面。

转到项目的“设置”页

  • 单击左侧的“集成与服务”

  • 在“服务”部分中，单击“添加服务”

    _images/github_integration_settings_1.png

  • 在可用服务列表中，单击“readthedocs”

  • 勾选“激活”

  • 点击“添加服务”

    _images/github_integration_settings_2.png

在“读取文档”中导入项目

登录阅读文档并单击“导入项目”。

_images/rtd_import_1.png

如果项目不在列表中，请选择手动导入：

_images/rtd_import_2.png

在GitHub中，将https克隆URL复制到剪贴板：

_images/github_https.png

返回“读取文档”，将URL粘贴到“存储库URL字段”，并填写项目名称：

_images/rtd_import_3.png

检查阅读文档版本

选中“读取”存储库相应地启用了文档版本。

_images/rtd_versions_1.png

需要时启用：

_images/rtd_versions_2.png

外部模块依赖项的AutoDoc修复

阅读文档在其环境中针对您的代码运行sphinx autodoc。因此，虽然autodoc可能在您自己的环境中运行良好，但由于导入的模块不存在，它可能在readthedocs中失败。

导入问题示例

在阅读文档时，我们可以看到示例模块，但不能看到示例模块2

我们检查了构建，它通过了。有什么问题？

点击阅读构建第4行的文档管理界面，我们看到：

_images/build1.png

进一步降低输出：

_images/build2.png

正确的。它失败了，因为colouredlogs模块没有安装在read the docs中。

如果这是一个问题，有几种方法可以解决这个问题。第一个更好：

使用virtualenv修复缺少的导入

在这个修复中，我们告诉readthedocs在虚拟环境中通过pip安装模块依赖项，然后运行sphinx autodoc。

在读取文档时启用virtualenv

登录阅读文档并进入设置->配置文件-><项目名称>

进入“管理”->“高级设置”并勾选“使用setup.py安装在virtualenv中安装项目”框。

在“requirements file:”框中填写requirements.txt

单击“提交”

创建requirements.txt文件

创建requirements.txt文件（ example ）在项目的根目录中。下面是安装coloredlogs库的示例requirements.txt文件：

# Install coloredlogs:
coloredlogs

用要用PIP安装的程序的名称替换coloredlogs。

用模拟修复丢失的导入

如果virtualenv解决方案不能完全从您那里工作，那么考虑使用mock。代码可以添加到docs/source/conf.py来模拟麻烦的导入，这样读取docs sphinx就不会在尝试加载它们时出错。

子模块必须列在其父模块之后，并且必须有来自顶层模块的完整列表。模拟ryu.base.app_manager的示例：

import mock

MOCK_MODULES = [
    'ryu',
    'ryu.base',
    'ryu.base.app_manager']

for mod_name in MOCK_MODULES:
    sys.modules[mod_name] = mock.Mock()