构建文档¶
首先克隆仓库¶
在构建文档之前，您必须首先克隆包含这些文件的仓库。
有关如何克隆仓库以便您可以在本地对其进行操作的说明，请参阅基础设施手册的 开始新项目的工作。
如果您在仓库设置方面遇到困难，请参阅 故障排除您的设置。
有关如何创建内容和贡献文档的详细信息，请参阅 编写文档。
本地构建输出¶
虽然您可以使用 Linux、MacOS 或 Windows 在本地构建 OpenStack 的 Sphinx 文档，但 Linux 是首选的构建环境，因为它为文档构建提供最全面的支持。
OpenStack 项目和文档仓库使用一个 tox.ini 文件，其中包含使用 Tox 工具（基于 virtualenv 的测试自动化）运行作业的特定部分。
安装构建文档的依赖项¶
OpenStack 维护一个名为 bindep 的工具，该工具维护着 Linux 包管理器依赖项的列表。当您运行 tox -e bindep 命令时，请阅读错误消息并根据返回的错误消息安装依赖项。继续运行，直到您的本地环境满足仓库中 bindep.txt 文件中列出的要求。
在 Ubuntu 或 Debian 上
# apt-get install python-pip # pip install tox $ tox -e bindep # apt-get install <indicated missing package names>
在 RHEL 或 CentOS 上（在 Fedora 上将 yum 替换为 dnf）
# yum install python-pip # pip install tox $ tox -e bindep # yum install <indicated missing package names>
在 openSUSE 或 SUSE Linux Enterprise 上
# zypper in python-pip # pip install tox $ tox -e bindep # zypper in <indicated missing package names>
注意
运行这些命令将安装构建 RST 和 PDF 文件所需的所有软件包。如果您不构建 PDF 文件，则不需要安装 texlive 软件包和 Liberation 字体系列。
在 MacOS 上
打开终端窗口。确保您已安装 Python。许多贡献者使用 Homebrew 工具说明。
$ brew install python $ pip install tox
注意
您无法在 Mac OS X 上运行 tox -e bindep，因为它使用 Linux 工具来解析信息。问题在此处记录。
在 Windows 上
要在 Windows 上按原样使用文档构建脚本，首先安装 Git for Windows。确保您拥有一个可用的 Python 环境，然后使用 Git Bash 在仓库目录中运行所有 tox 命令
$ pip install tox
openstack-manuals 的构建工作流程¶
安装并配置 Tox 后，执行 tox -e <jobname> 以运行特定的作业。例如，要构建 openstack-manuals 中的所有指南，请运行以下命令
$ tox -e docs
仓库中的 README 文件详细解释了您可以运行的各个 Tox 作业。
作为审查过程的一部分，OpenStack CI 系统运行脚本以检查补丁是否正常。在本地，您可以使用 Tox 工具来确保补丁有效。要检查所有指南，请从仓库的根目录运行 tox 命令。
具有文档的其他仓库的构建工作流程¶
安装并配置 Tox 后，执行以下命令以运行 docs 作业
$ tox -e docs
构建完成后，它会将构建的文档输出到 doc/build 目录。您可以在浏览器中打开构建的 .html 文件来查看它们。
本地构建现有补丁¶
要在本地构建补丁
在您克隆的适当仓库中，创建一个包含特定补丁的本地分支。
$ git review -d PATCH_ID
其中
PATCH_ID的值是 Gerrit 提交编号。您可以在补丁链接https://review.opendev.org/#/c/PATCH_ID上找到此编号。构建受补丁集中更改影响的文档。有关更多信息，请参阅 openstack-manuals 的构建工作流程 和 具有文档的其他仓库的构建工作流程。
构建作业¶
文档的构建作业存储在 project-config 仓库中。构建作业构建到 docs.openstack.org 和 developer.openstack.org 站点，并通过 FTP 复制构建的文件。
特定于发布的指南是为当前支持的分支（当前和先前版本）构建的，开发在主分支上进行。持续发布的指南仅在主分支上构建。
与其他项目一样，文档项目使用许多执行补丁自动测试的作业。
对于 openstack-manuals，当前的作业是
openstack-tox-linters
build-tox-manual-publishdocs
build-tox-manual-publishlang
Publishlang 作业¶
我们仅对翻译充分的手册/语言组合进行门控。
如果从 Zanata 的导入失败，我们不会批准该导入。
如果任何其他补丁失败，则该失败可能会被忽略。
在任何情况下发生故障，都会针对 i18n 项目报告一个错误。
如果您想在 openstack-manuals 的克隆中手动运行此检查，请使用 publishlang 环境 (tox -e publishlang)。
从已停止支持的发布版本构建文档¶
OpenStack 项目可以遵循不同的 发布模型。openstack-manuals 仓库遵循这些模型中的两个，即独立和周期性里程碑。
注意
文档仓库和 api-site 遵循独立的发布模型。
要从特定发布版本在本地构建文档，请按照以下步骤操作。
在您克隆的适当仓库中，查看远程标签以查看每个发布的标签
$ git tag -l 2012.1 2012.2 2013.1.rc1 2013.1.rc2 2013.2 diablo-eol essex-eol folsom-eol grizzly-eol havana-eol icehouse-eol juno-eol kilo-eol liberty-eol
查找您想要构建的发布名称，例如 Essex，并签出相应的标签
$ git checkout essex-eol
Git 签出文件并在完成后，会向您显示本地文件的参考点，例如
HEAD is now at e6b9f61... fix delay_auth_decision parameter。阅读该时间点可用的
README.rst文件，了解在本地构建文档的先决条件。例如，您可能需要安装 Apache Maven 才能构建旧文档。
