在站点之间统一 OpenStack 主题

更新日期：2018-12-06 13:55

在各个站点合并 OpenStack 主题¶

问题描述¶

当读者访问 docs.openstack.org 上的页面时，他们可能会看到两种主题对页面进行样式设置：oslosphinxtheme 或 openstackdocstheme。对于单个子域名使用两种主题，我们无法为网站访问者提供一致的体验。每个页面的顶部和侧边栏提供的导航会因这两个主题而异，并且现在 OpenStack 本身有一个新的徽标，我们希望将这两个主题合并为一个主题，即 openstackdocstheme。

此外，从维护的角度来看，继续支持两个主题意味着我们必须维护并为两个 Sphinx 主题提供错误修复，而我们的 Web 开发资源有限。

提议的变更¶

以下是概述了所有使用单个主题一致地构建到 docs.openstack.org 的文档所需的任务。

主题工作

更新 openstackdocs 主题以匹配 www.openstack.org 上使用的徽标。

openstackdocstheme 中当前不存在的用户界面更改

在输出的页脚中提供构建文档的版本号。例如，“tempest 15.0.1.dev359 documentation”出现在 Tempest 文档的每个页面上。目前，openstackdocstheme 仅提供构建日期，而不提供构建版本号。
与 www.openstack.org 上当前使用的徽标匹配的新徽标。

将不会从 oslosphinx 移植到 openstackdocstheme 的用户界面差异

左侧导航栏底部的快速搜索表单。
左侧导航栏中显示的上一个主题和下一个主题。
左侧导航栏中的返回项目主页链接。
页眉中自定义的链接列表。例如，https://docs.openstack.org/infra/system-config/ 上的页面包含自定义页眉。
当像 https://docs.openstack.org/infra/ 这样的着陆页使用 oslosphinx 时，应该使用新主题重新设计该页面。

配置工作

让所有构建到 docs.openstack.org 子域的项目使用 openstackdocstheme 主题，而不是 oslosphinx 主题。基本上，更新所有文档页面的 conf.py 文件以使用 openstackdocstheme。

确保错误配置正确，以便当读者单击构建的文档中的“报告错误”链接时，将打开相应项目的错误记录位置。

弃用 oslosphinx 主题的维护和使用，并在 openstackdocstheme 中解决该主题满足的任何独特需求。

维护或项目工作

将 oslosphinx 主题的待办事项列表中的任何错误移动到 https://bugs.launchpad.net/openstack-doc-tools 处的 openstack-doc-tools 错误队列。

备选方案¶

继续使用和维护两个主题，一个用于贡献者文档，一个用于消费者文档。

更改 oslosphinx 主题以像 openstackdocstheme 一样设置所有内容，基本上是执行上面提出的主题使用方式的相反操作。如果发现更多的 conf.py 文件使用 oslosphinx 主题，我们可以考虑这种方法。

实现¶

负责人¶

工作项¶

将此规范传达给项目团队。

确定一个奥斯陆联络人，以帮助处理任何依赖于审查的问题。

确保“丢失”界面项目的列表是可以接受的，并且该列表本身是完整的。如果不是，则应修改此规范和列表。

上述主题工作。

上述配置工作。

上述维护工作。

依赖项¶

确保其他奥斯陆库没有依赖于主题的依赖项。

测试¶

测试在使用 openstackdocstheme 处理所有不同类型的内容时，翻译是否继续有效。

参考资料¶