Sphinx文档

Sphinx - Python Documentation Generator 是我主要的文档撰写工具，功能强大，我仅仅使用了部分功能来完成 云图 – 云计算图志 撰写。

警告

我在使用readthdocs.io平台构建sphinx文档时，在2021年10月开始遇到build fail，参考 Build Failed. TypeError: ‘generator’ object is not subscriptable #8616 :

  • 对于2020年10月之前创建的Sphinx项目，RTD会使用Sphinx<2的版本，此时如果你更新过pip环境，docutils-0.18 就会不兼容，导致 RTD 编译失败

  • 解决方法是明确指定RTD环境，参考 RTD eproducible Builds 特别是 RTD pinning dependencies

我依然觉得我需要学习和不断实践，才能相对较为合理地使用好这个工具。所以，我汇总我的一些实践，以便不断提高撰写技巧。