模板生成器详情

docs.openstack.org 上未作为 Sphinx 构建的文档集管理的内容，通过 openstack-manuals git 仓库中的 tools/www-generator.py 中的自定义模板渲染工具处理。

该脚本读取 www/project-data 中的 YAML 数据文件，以确定给定系列中存在哪些项目以及如何在安装、配置和其他指南的列表中显示它们。

在脚本加载有关外部项目的数据后，它会扫描 www/ 目录中的 HTML 模板文件。它使用 Jinja2 将模板转换为完整的 HTML 页面，并将其写入 publish-docs 输出目录。

参见

Jinja2 文档包含一个模板设计人员指南，涵盖模板的语法、模板之间的继承以及编写模板时可用的各种过滤器和其他功能。

模板文件

openstack-manuals 仓库中的模板文件都位于 www 目录中。它们以与发布到站点相同的方式组织，因此发布的 URL 路径直接对应于生成它的模板文件路径。

以下是 www/ 下的一些代表性文件

  • austin

    • index.html – $series 文档的着陆页（每个系列一个）

  • de

    • index.html – 翻译成 $LANG 的指南列表

  • errorpage.html

  • mitaka – 较新的系列具有更复杂的页面组织；每个目录都是唯一的

    • admin（管理员）

      • index.html

    • api

      • index.html

    • de

      • index.html – 翻译成 $LANG 的 $series 文档的着陆页

    • index.html

    • language-bindings.html

    • projects.html

    • user

      • index.html

  • pike

    • admin（管理员）

      • index.html

    • api

      • index.html

    • 配置

      • index.html

    • deploy

      • index.html

    • index.html

    • install

      • index.html

    • language-bindings.html

    • projects.html

    • user

      • index.html

  • project-data – 包含每个 $series 中项目数据的 YAML 文件

    • latest.yaml

    • mitaka.yaml

    • newton.yaml

    • ocata.yaml

    • pike.yaml

    • README.rst

    • schema.yaml

  • redirect-tests.txt – whereto 的输入文件，用于测试 .htaccess。要查看最近的 404 错误，请检查 Zuul 中 docs-openstack-goaccess-report 构建的“Goaccess 报告”制品。要搜索此作业的最新运行情况，请访问 Zuul 构建页面。

  • static – 包含不是模板的文件（CSS、JS、站点地图等）

  • templates – 包含重用的模板（基本页面、部分页面等）

    • api_guides.tmpl

    • base.tmpl

    • contributor_guides.tmpl

    • css.tmpl

    • default.tmpl

    • dropdown_languages.tmpl

    • footer.tmpl

    • google_analytics.tmpl

    • header.tmpl

    • indexbase.tmpl

    • navigation.tmpl

    • ops_and_admin_guides.tmpl

    • project_guides.tmpl

    • script_footer.tmpl

    • script_search.tmpl

    • series_status.tmpl

    • os_search_install.tmpl

    • os_search_mobile.tmpl

    • os_search.tmpl

    • training_guides.tmpl

    • user_guides.tmpl

定义发布系列

发布系列及其各自的状态和其他元数据嵌入在模板生成器脚本中的 SERIES_INFO 数据结构中。该结构是一个字典，将发布系列名称映射到包含元数据的 SeriesInfo 结构。

对于每个发布系列，生成器需要知道

date

日期值应包含月份名称和 4 位年份的字符串。

status

“status”字段应为以下之一

obsolete

该发布存在，但我们不再有它的制品

EOL

该发布已关闭，但我们有它的文档

maintained

该发布仍有一个开放的分支

development

当前正在开发的发布

参见

更新发布结束时的 www 页面 包含有关如何在发布周期结束时更新状态值的一些其他信息。

项目数据文件格式

与每个发布系列关联的项目在 www/project-data 目录中的单独的 YAML 文件中列出。每个文件都以该系列命名（austin.yaml、bexar.yaml 等），除了当前正在开发的系列，该系列始终保存在 latest.yaml 中。

项目数据文件的模式定义在 www/project-data/schema.yaml 中。

每个文件应包含一个数组或列表条目。每个条目必须定义 name、service 和 type 属性。

name 应是 git 仓库的基本名称。

deliverable-name 应如 openstack/governance/reference/projects.yaml 中定义的可交付项名称。仅当可交付项名称与项目名称不匹配时（例如 glance_store 和 glance-store）才需要设置此值。

service 字符串应从治理仓库的项目定义中获取。

type 必须是以下值之一

服务

REST API 服务。

cloud-client

用于与云通信的库。

service-client

用于与服务通信的库。

library

另一种类型的库。

tool

命令行工具或其他与 OpenStack 一起使用或用于构建 OpenStack 的项目。

networking

网络服务的一个插件。

baremetal

裸机项目 Ironic 的子项目。

deployment

用于部署 OpenStack 的工具。

other

在云中运行但不提供 REST API 的项目。

条目还可以选择定义 service_type，它必须与 service-types-authority 仓库 中名称关联的值匹配。

对于 type 设置为 client 的条目，应包含一个 description 字段，其中包含简短的描述，例如“keystone client”。

条目可以可选地设置标志，以指示仓库包含特定类型的文档在预期位置，以便在模板化着陆页上包含指向该文档的链接。

has_install_guide

生成指向 docs.o.o/{{name}}/2025.2/install/ 的链接

has_api_guide

生成指向 developer.o.o/api-guide/{{service_type}}/ 的链接

has_api_ref

生成指向 developer.o.o/api-ref/{{service_type}}/ 的链接

has_config_ref

生成指向 docs.o.o/{{name}}/2025.2/configuration/ 的链接

has_in_tree_api_docs

生成指向 docs.o.o/{{name}}/2025.2/api/ 的链接

has_admin_guide

生成指向 docs.o.o/{{name}}/2025.2/admin/ 的链接

has_in_tree_htaccess

启用完全重定向到旧路径，而不仅仅是重定向到 /{{name}}/2025.2/ 的顶部

has_deployment_guide

生成指向 docs.o.o/project-deploy-guide/{{name}}/{{series}}/ 的链接

注意

必须在设置标志之前存在与标志关联的文档。

模板变量

模板生成器使用输入数据设置模板中可见的几个变量。这使我们能够重用相同的模板来生成相同风格的多个页面，并填充不同的数据。

按照惯例，模板生成器定义的所有变量都使用大写名称。这使得区分生成器变量和模板中定义的变量（例如循环上下文）变得容易。

TEMPLATE_FILE

正在渲染的模板文件的名称，去除了 www 前缀。例如，pike/index.html。

PROJECT_DATA

从数据文件中加载的所有项目数据，映射到系列名称和解析数据文件的字典。大多数模板页面将使用 PROJECT_DATA[SERIES] 分配一个局部变量，以提取正确的数据子集。

TOPDIR

构建输出的顶部路径（默认情况下为相对路径，使用 --publish 选项为绝对 URL）。这对于以允许这些页面稍后移动的方式在输出页面之间构建路径很有用。

SCRIPTDIR

JavaScript 目录在构建输出中的位置的路径（默认情况下为相对路径，使用 --publish 选项为绝对 URL）。这对于构建到 JavaScript 文件的链接很有用。

CSSDIR

CSS 文件所在的目录在构建输出中的位置的路径（默认情况下为相对路径，使用 --publish 选项为绝对 URL）。这对于构建到 CSS 文件的链接很有用。

IMAGEDIR

图像文件所在的目录在构建输出中的位置的路径（默认情况下为相对路径，使用 --publish 选项为绝对 URL）。这对于构建到图像的链接很有用。

SERIES

一个包含可在 URL 中使用的系列名称的字符串。对于正在开发的系列，此值为 "latest"。对于其他系列，它是系列名称的小写形式。

此值是从模板文件的路径派生的。如果该文件位于与已知系列名称之一匹配的目录中，则该值用于设置 SERIES。

SERIES_TITLE

一个包含可在读者可见的文本中使用的系列名称的字符串。它始终是“标题大小写”形式的实际系列名称（每个单词的首字母大写）。例如，"Pike"。

此值是从模板文件的路径派生的。如果该文件位于与已知系列名称之一匹配的目录中，则该值用于设置 SERIES。

ALL_SERIES

OpenStack 所有发布的所有系列名称的列表，按发布顺序排列。

此列表是从模板生成器中 SERIES_INFO 字典的键派生的。

PAST_SERIES

OpenStack 发布中状态不为 "development" 的系列名称的列表。

此列表是从模板生成器中 SERIES_INFO 字典的值派生的。

RELEASED_SERIES

最近发布的系列的名称的小写字符串。例如，在 Pike 系列期间，此值为 "ocata"。

此值是从模板生成器中 SERIES_INFO 字典的值派生的。

SERIES_IN_DEVELOPMENT

当前正在开发的系列的名称的小写字符串。例如，在 Pike 系列期间，此值为 "pike"。

此值是从模板生成器中 SERIES_INFO 字典的值派生的。

SERIES_INFO

与当前系列关联的 SeriesInfo 对象。这提供了对系列 date 和 status 值的访问权限。

此值取自模板生成器中定义的 SERIES_INFO 字典。

REGULAR_REPOS

官方 OpenStack 项目的常规仓库的所有名称的列表。这里，“常规”将仓库与基础设施团队仓库区分开来，其文档发布到不同的位置，因此需要 .htaccess 模板中的一些不同的 URL 重定向。请参阅 INFRA_REPOS。

此值是从治理仓库发布的数据派生的。

INFRA_REPOS

基础设施团队仓库的所有名称的列表。请参阅 REGULAR_REPOS。

此值是从治理仓库发布的数据派生的。

常见任务

如何更改页面？

  1. 查找页面源代码中的 TEMPLATE_FILE 值，以找到生成该页面的文件。

    https://docs.openstack.org/2025.2/ 的源代码显示

    <!-- TEMPLATE_FILE: openstack-manuals/www/2025.2/index.html -->

  2. 修改该文件或它继承的任何其他模板。

    www/2025.2/index.html 具有基础模板 www/templates/indexbase.tmpl，其中包含

    {% include "templates/series_status.tmpl" %}

    并且该指令会引入 www/templates/series_status.tmpl。

如何添加一个新项目？

修改 www/project-data/latest.yaml 以添加新的条目。

各种类型的文档的标志默认关闭；仅列出应开启的标志。设置项目的类型，以确保它出现在正确的列表（们）中。

如何向项目元数据添加一个新标志？

  1. 通过修改 www/project-data/schema.yaml 来更新模式，以允许该标志。

  2. 修改文档团队贡献者指南，通过修改 doc/doc-contribu-guide/source/doc-tools/template-generator.rst 来解释该标志的用途。

  3. 更新 www/project-data/latest.yaml 以为某些项目设置该标志。

  4. 更新/创建将使用该标志的模板。

如何添加新页面？

将现有的模板文件复制到 www/ 下的新名称，然后进行修改。

最终发布流程是怎样的？

请参阅 发布任务详情。

测试构建

有两条命令可用于在本地测试构建

$ tox -e publishdocs

和

$ tools/test.sh

测试脚本支持一些选项，使其更有效。

--skip-links

跳过链接检查

--series SERIES

要更新/测试的系列

--check-all-links

检查标志设置为 false 的链接。

为了测试模板渲染，而无需等待链接检查

$ ./tools/test.sh --skip-links

为了仅测试 latest.yaml 中列出的项目的链接

$ ./tools/test.sh --series latest

为了生成一个未设置的 latest.yaml 标志的列表，这些标志可以设置（链接的页面确实存在）

$ ./tools/test.sh --check-all-links --series latest