使用Sphinx、Github和Read the Docs(RTD)可以共同构建一个文档自动化生成工具。

其中Sphinx负责使用reStructedText语法来生成对应的HTML文档。尤其是在python文档生成时会使用import来导入整个包,并搜索对应的注释文档。

将sphinx共同上传到github项目中并链接RTD账户,生成并托管项目文档。每当github有更新时,RTD会同步生成重建新的文档。

在RDT具体生成文档时,依照以下流程:

资源拉取

首先,创建一个虚拟环境,并拉取你github项目的内容。以下是RTD构建的详细信息。同时会临时创建一个python虚拟环境用于导入包。

从gtihub拉取资源

配置环境

安装你要发布包的依赖,即安装requirements.txt清单。RTD的项目高级管理中,可以选择需要安装的requirements.txt路径。

选择依赖文件列表的路径

安装自定义包

pip install 安装你要发布包的依赖。其中包括你在setup.py文件里写的环境依赖。在这一步你的需要保证你的setup.py安装过程是正确的。

导入自定义包

安装好自定义包后,会自动import导入一下,完成对注释文档的拉取。到此构建过程结束。

内存消耗问题

整个资源拉取、配置环境、安装以及导入自定义包的过程在RTD中都是可以看到的,例如,如下就是一个构建失败的例子,原因是RTD提供的虚拟环境的内存很小,包的安装需要太多依赖。

如果你的自定义包是依赖于像tensorflow或pytorch这样几百兆的大包,那么在安装依赖这一过程一定会出现内存耗尽的问题。然而,不安装这些依赖,你的自定义报又无法正确import(会提示你找不到xxx包)。无法正确import自定义包就无法抓取注释文档并生成文档。

解决方法

原文链接在这里:

How to: Make your Sphinx documentation compile with ReadTheDocs when you’re using Numpy and Scipy

有一些太大无法导入,或是依赖C扩展的包,可以使用 mooc 来虚拟所需要的包。
例如:

import mock

MOCK_MODULES = ['numpy', 'scipy', 'matplotlib', 'matplotlib.pyplot', 'scipy.interpolate']
for mod_name in MOCK_MODULES:
sys.modules[mod_name] = mock.Mock()

因为,我们在生成文档的时候并不需要执行任何代码,而只是import这个包。所以,虚拟包在实际执行时会出错,但是仅仅用于import导入是完全可以的。在sphinx的conf.py文件中使用Mock来虚拟所需要的包,让这些包在生成文档时对本地可见。

需要注意的一点是 from xxx import * 或 from xxx import xxx 这种形式的导入。

原文解释如下:

However, the code that is provided by ReadTheDocs doesn’t work for any modules that you import using the * operator – for example, from matplotlib import *.

即,你需要在mock中虚拟出每一个使用到的子包。例如:

'matplotlib.pyplot', 'scipy.interpolate'