从基于 rst 的指南文档构建 PDF 文档¶

问题描述¶

DocBook XML 文件已成功迁移并转换为 RST 源代码。OpenStack RST 源代码文档使用 Sphinx 构建 HTML 文档并在 docs.openstack.org 上发布。openstackdocstheme 负责已发布 HTML 文档的主题和扩展。

在基于 RST 的文档中期望的功能之一是拥有书籍的 PDF 版本。当前的 HTML 文档当然很有帮助，但拥有 PDF 版本可以为 OpenStack 文档读者提供更多额外的优势。例如，用户可以下载 PDF 文件并离线阅读。要打印 HTML 文档，用户需要执行更多手动步骤，例如从一页移动到另一页，并且打印布局与用户通过监视器看到的内容不同。此外，用户更容易将个人笔记以 PDF 文件的形式与其他读者共享。使用 PDF 文件的另一个优势是 PDF 文件有页码。这对于带有可打印 OpenStack 文档的离线培训环境很有用，通过指示页码。

提议的变更¶

添加使用当前 Sphinx 构建基础设施，使用 openstack-manuals 仓库中的基于 RST 的文件构建 PDF 的支持。

使用基于 RST 的文件生成 PDF 文件包括工作流中的两个步骤。首先，Sphinx 从基于 RST 的文件生成 LaTeX 文件 (.tex)。其次，pdflatex 从生成的 LaTeX 文件生成 PDF 文件。

在 Sphinx 和 LaTeX 的组合支持 PDF 文件生成之后，将 PDF 构建应用于 openstack-manuals 仓库中的所有 HTML 文档，使用 LaTeX PDF 生成。并添加构建作业与 HTML 构建协同工作，在每次文档构建时在 docs.openstack.org 上发布 PDF 文件，最后在 HTML 文档的登陆页面中插入 PDF 下载链接。

请注意，主要更改将发生在 openstack-doc-tools 中用于脚本，openstackdocstheme 中用于 PDF 可能的附加主题，以及每个文档仓库（例如 openstack-manuals）中，以在 Sphinx 配置中添加 PDF 构建支持。

实现¶

项目范围¶

• 此规范主要侧重于应用于 openstack-manuals 仓库中的文档。security-doc 和 api-site 也是构建 PDF 的良好目标，但它们不在本规范的范围内。

• 从翻译文档构建 PDF 的支持不在范围内。

• 对于一个基本的 PDF 主题，以下要求不在范围内。

  • 带有页码的索引
  • 标题页上的 OpenStack 徽标显示（选择适用于每个交付品的适当徽标会很繁琐）
  • 可选：水印以指示草稿或文档适用的版本

依赖项¶

• 可能取决于 pdf 构建程序（例如，LaTeX）

测试¶

• 将作为构建的一部分对工具进行测试。
• 对 PDF 文件进行 Beta 阅读和反馈将有助于检查布局问题，例如图像分辨率较低和表格显示问题。

参考资料¶

• http://lists.openstack.org/pipermail/openstack-docs/2016-July/008867.html
• http://lists.openstack.org/pipermail/openstack-docs/2016-July/008869.html
• https://review.openstack.org/#/c/396943/