RFC 74:将gdal.org迁移到RTD样式的Sphinx基础结构

作者：	霍华德巴特勒
联系方式：	howard@hobu.co
起动：	2019年5月19日
状态：	采用

总结

该文档建议将GDAL文档从Doxygen迁移到 Sphinx 在里面 ReadTheDocs 格式。

动机

对GDAL文档的临时贡献是有挑战性的。Wiki风格的贡献可以通过Trac实例实现，但这需要获得OSGeo登录，这是一个高条，Trac信息与主文档断开连接。其他项目，如PROJ和 MapServer 通过采用基于Sphinx的系统，已经看到贡献文档的显著增长，我们希望GDAL采用这种方法将点燃文档贡献的复兴，就像它对这些项目所做的那样。

目前的方法有一些重大的缺陷，但还没有通过等待新版本的Doxygen的到来来克服。其中包括：

Doxygen构建将文档的源代码深埋在源代码树中，这使得很难找到正确添加信息的位置。
网站的结构与创建它的源代码是间接的。
新功能，如方便的移动友好的样式、PDF等替代序列化，以及更紧密的API和用户级文档集成，并非易事。
编辑原始HTML意味着其他序列化类型（如PDF、Windows编译的帮助或manpage输出）的方便输出是一项挑战。

提案

GDAL团队将重构GDAL.org网站，使其基于Sphinx，具有以下属性：

将现有文档的大部分转换为reStructuredText
适应 ReadTheDocs theme
将“在GitHub上编辑此页面”链接应用于网站上的每个页面，以方便您做出贡献
利用 GitHub Pages 托管gdal.org，更新由 Azure Pipelines 持续整合。
输出网站的PDF序列化以供文档版本的后代使用。

考虑事项

源代码中存在许多指向驱动程序页的硬链接。必须注意尽量保留这些链接，并通过重定向来适应任何新的组织。
将现有的Trac内容移植到新的数据结构将允许该基础结构的退役。要实现这一点，可能需要大量的内容移植投资。
Doxygen API风格的文档仍然很有价值，我们建议将它们的呈现保持在 /doxygen 对于希望继续使用这种方法的用户。内部API文档将继续使用Doxygen，它将使用Breathe功能反映到Sphinx网站中。
最初的内容组织将试图模仿现有的网站以及可以实现的，但如果其他组织方法更方便，考虑到 Shpinx 的功能和能力，则不需要保持对先前结构的遵守。
现有的翻译将不会被移植。翻译移植的改编和延续超出了本RFC的范围，但是Sphinx中有管理翻译的功能（MapServer.org提供了一个很好的例子），一旦完成了最初的工作，后续贡献者可以继续推进架构。
在转换过程中可能会丢失内容。请在GitHub中为任何在转换后变得更难找到或消失的项目提交票据。

物流

该网站的当前示例位于 https://gdal.dev 此示例设置为noindex。一旦通过RFC，构建它的基础设施的适应将迁移到 https://gdal.org 示例网站将完全退役。目前， https://github.com/hobu/gdal doc-sprint branch是驱动此内容的fork。它将在RFC通过时被压缩合并到主存储库。

参考文献：

投票历史

+1名来自库尔特、豪瓦德、丹尼尔姆、诺曼布、朱卡尔和埃文。