Question

我在ReadTheDocs上有一个项目。

作为文档生成的一部分，我让Sphinx使用matplotlib的plot directive编译大量图像，显示各种命令的作用。似乎这需要比RTD为构建过程分配更多的内存。我正在试图弄清楚该做些什么。

我的想法：

我可以支付RTD以增加内存限制。但我是一名小型开发人员，从事精品分析工具，他们的计划很昂贵。
我可以为我的数字生成切换到较小的数据集，并希望它使用更少的内存。如果图像数量增加或计算复杂性增加，这种猜测和检查策略令人沮丧，无论如何都可能无法持续。
我可以将静态生成的图像提交给现有的repo，并且只有在静态图像不存在的情况下，才能将生成新图像的扩展程序混合在一起。但是我不喜欢这个，因为现在我的代码回购会因为某些原因每次需要更改图像时都会增长，而且我更喜欢保持repo轻量级。
我可以将编译后的文档提交到某种单独的repo并将其上传到RTD。这可以防止每次图像更改时代码库都会增长。但是，我不知道如何告诉RTD这个文档。

在ReadTheDocs项目中包含计算成本高昂的自动生成图像的好方法是什么？

Answer 1

面值，选项3是最好的方法。如果生成图像的计算成本很高，显然您希望减少这些计算。此外，你不应该存储图像。这听起来像是要将该逻辑推送到部署提供程序。请记住，图像也可以缓存在用户的计算机上，因此无需重新生成未更改的图像。

现在，另一个选择是使用像plot.ly这样的JavaScript库。生成图像或图表计算成本高吗？如果生成图表很便宜，那么切换到JavaScript库是可行的方法。

关于选项4：如何做到in the documentation。

Answer 2

我最终选择了选项4。

为此，我通过以下方式修改了matplotlib的Sphinx plot directive。

我添加了一个选项，以便用户可以指定图像的输出名称。这消除了关于哪个图像与哪个代码块相关联的模糊性。
我添加了一个配置选项，它将命名输出图像的副本放在一个可以进行版本控制的单独目录中。在运行用户的图形生成代码之前，将此目录中的图像复制到构建输出中;这预先占用了运行代码的需要，减少了计算时间。

然后我修改了我的Sphinx conf.py文件以加载并使用这个新的绘图模块。

最后，我将生成的图像保存在子模块中。

为了更新文档，我现在使用以下工作流程：

在本地运行make html。
提交对图像子模块的更改并将其推送。
提交主要仓库的更改并推送它。这会触发RTD重建。
RTD自动加载子模块，因此获取计算成本高的图像并在其构建服务器上运行make html。但是，如果图像存在，则不会进行密集计算。

已修改conf.py

#This line tells Sphinx to look for modules in the directory
#containing `conf.py`. This way it finds `plot_directive.py`
sys.path.append(os.path.abspath('.'))

#This must come before plot_directive is loaded by Sphinx
plot_preserve_dir = 'imagery-submodule-directory'

extensions = [
  #...
  'plot_directive',
  #...
]

我的plot_directive.py修改版可用here。

ReadTheDocs内存不足

2 个答案: