在Sphinx中保持API更新

问题描述

方案如下。有一个名为foo的包(一个正在大量开发的API，处于第一个Alpha阶段)，它的rst文件是使用sphinx-apidoc自动生成的。

为了在生成这些文件后获得更好的foo文档，需要进行一些编辑。比方说，在foo.bar.rst中，有一些段落添加到sphinx-apidoc生成的内容中

进行sphinx-apidoc新调用时，如何才能不丢失所有信息？当然，我希望反映API中的潜在更改，并保留添加的手动信息。

---

解决方案

sphinx-apidoc仅当项目的模块结构发生变化时才需要重新运行。如果添加、删除和重命名模块对您来说并不常见，那么最简单的方法可能是将rst文件置于版本控制之下，然后手动更新它们。添加或删除模块只需要更改几行rst，因此运行一次后甚至不需要使用sphinx-apidoc。