重定向文档

自 Pike 版本发布以来，由于 doc-migration，链接重定向变得至关重要。这次迁移将大量文档从 openstack-manuals 仓库迁移到各自的项目仓库。然而，这次内容迁移破坏了许多外部（和内部）链接。

将 .htaccess 文件添加到你的仓库

第一步是添加 Apache 所需的 .htaccess 配置文件，以便 Apache 知道重定向规则是什么。openstack-manuals 在 openstack-manuals 仓库中有一个全局文件，但我们还配置了 Apache，允许每个项目的文档中都有一个 .htaccess 文件。

如果在项目中包含一个 .htaccess 文件，则需要告诉 Sphinx 在构建输出中包含该文件，方法是将其添加到 extra 文件列表中。 这个补丁 展示了 nova 是如何通过编辑 doc/source/conf.py 来设置 html_extra_path 的。如果路径设置为 _extra，则该补丁还应创建 doc/source/_extra/.htaccess，其中包含所需的重定向。该文件的内容可以手动编写，也可以使用 命令计算。

注意

如果你想在 gate 中的 build-openstack-sphinx-docs 作业中使用 whereto 工具，你必须将你的 .htaccess 文件放在 _extra 中。（这不是 Sphinx 的要求，而是 gate 作业设置的要求。）

虽然此文件是一个真正的 .htaccess 文件，但预计该文件只会包含使用 Redirect 和 RedirectMatch 规则的重定向。例如，下面显示了 nova 项目的一些重定向，反映了 Ocata 和 Pike 版本之间移动的文件

redirectmatch 301 ^/nova/([^/]+)/aggregates.html$ /nova/$1/user/aggregates.html
redirectmatch 301 ^/nova/([^/]+)/architecture.html$ /nova/$1/user/architecture.html
redirectmatch 301 ^/nova/([^/]+)/block_device_mapping.html$ /nova/$1/user/block-device-mapping.html
redirectmatch 301 ^/nova/([^/]+)/cells.html$ /nova/$1/user/cells.html
redirectmatch 301 ^/nova/([^/]+)/conductor.html$ /nova/$1/user/conductor.html
redirectmatch 301 ^/nova/([^/]+)/feature_classification.html$ /nova/$1/user/feature-classification.html
redirectmatch 301 ^/nova/([^/]+)/filter_scheduler.html$ /nova/$1/user/filter-scheduler.html
redirectmatch 301 ^/nova/([^/]+)/placement.html$ /nova/$1/user/placement.html

此文件将确保为诸如 /nova/2025.2/aggregates.html 到 /nova/2025.2/user/aggregates.html，以及 /nova/2025.2/cells.html 到 /nova/2025.2/user/cells.html 等路径启用重定向。

为你的项目启用详细重定向

自 Pike 版本和 doc-migration 以来，所有位于 /developer/$project/ 下的内容都已移动到 /$project/2025.2/（其他版本也有类似的移动）。默认情况下，任何位于 /developer/$project/ 下的页面现在都会被重定向到 /$project/2025.2/。这为用户提供了一个目录表来查找新页面。

在将本地 .htaccess 文件添加到项目的文档后，可以将 /developer/$project/(.*) 重定向到 /$project/2025.2/$1，然后该页面将再次重定向到文件的新的位置。

要启用此功能，请修改 openstack-manuals 仓库中的 www/project-data/latest.yaml 文件，为仓库设置 has_in_tree_htaccess 标志。有关可以设置以控制你的项目在 docs.openstack.org 上显示方式的其他标志的详细信息，请参阅 模板生成器详情。

在 has_in_tree_htaccess 标志更改生效后，对诸如 docs.openstack.org/developer/nova/cells.html 之类 URL 的链接应该（通过两次重定向）最终到达新的位置 docs.openstack.org/nova/2025.2/user/cells.html。

测试你的重定向

可以使用 whereto 工具来测试你的重定向。由于你显然希望对其进行测试，因此 build-openstack-sphinx-docs 作业已经设置为在 gate 中使用 whereto，并且每当 whereto 存在于项目的依赖列表中时，都会自动在 docs 构建作业上运行 whereto。因此，要启用重定向测试，你只需要将 whereto 添加到你的仓库的 doc/requirements.txt 或 test-requirements.txt 文件中。

但是，要使作业通过，你必须确保 build-openstack-sphinx-docs 作业可以找到 whereto 期望的输入文件。这些文件是

  • Apache 重定向文件。构建作业期望此文件名为 .htaccess 并且位于 doc/source/_extra 目录中。

  • 测试文件。构建作业期望此文件名为 test-redirects.txt 并且位于 doc/test 目录中。

为了方便开发人员在本地运行构建，你可以在项目的 tox.ini 文件中添加一个显式的 whereto 调用。（这个 glance-specs 补丁 提供了一个示例。）

可选：从 Git 生成 .htaccess 文件

如果正在创建初始 .htaccess 文件，可以使用一些 Git 命令来自动生成一个包含从上一个版本到当前版本的重定向的文件。例如，要为 nova 项目生成一个重定向列表，用于在 Ocata (stable/ocata) 和当前 HEAD（假定为 Pike）之间移动的文件，请运行

$ git log --follow --name-status \
  --format='%H' origin/stable/ocata.. \
  -- doc/source | \
      grep ^R | \
      grep .rst | \
      cut -f2- | \
      sed -e 's|doc/source/|^/nova/([^/]+)/|' \
          -e 's|doc/source/|/nova/$1/|' \
              -e 's/.rst/.html$/' \
              -e 's/.rst/.html/' \
              -e 's/^/redirectmatch 301 /'

输出如下所示

redirectmatch 301 ^/nova/([^/]+)/aggregates.html$ /nova/$1/user/aggregates.html
redirectmatch 301 ^/nova/([^/]+)/architecture.html$ /nova/$1/user/architecture.html
redirectmatch 301 ^/nova/([^/]+)/block_device_mapping.html$ /nova/$1/user/block-device-mapping.html
redirectmatch 301 ^/nova/([^/]+)/cells.html$ /nova/$1/user/cells.html
redirectmatch 301 ^/nova/([^/]+)/conductor.html$ /nova/$1/user/conductor.html
redirectmatch 301 ^/nova/([^/]+)/feature_classification.html$ /nova/$1/user/feature-classification.html
redirectmatch 301 ^/nova/([^/]+)/filter_scheduler.html$ /nova/$1/user/filter-scheduler.html
redirectmatch 301 ^/nova/([^/]+)/placement.html$ /nova/$1/user/placement.html

对于好奇的人来说，这个脚本的工作原理如下

  1. git log 命令遍历自切割 stable/ocata 分支以来 master 的 Git 历史记录，跟踪 doc/source 下的文件在重命名时的变化，并显示更改的哈希值以及文件的名称和状态。输出如下所示

    2f36a355f29cb9f23beb2b80399e59f02d3c17a3
M       doc/source/_extra/.htaccess
M       doc/source/index.rst
R100    doc/source/user/cellsv2_layout.rst      doc/source/user/cellsv2-layout.rst
M       doc/source/user/index.rst

  2. grep 命令过滤以 R 开头的行（表示文件已重命名）以及以 .rst 结尾的文件（以限制为文档文件）。输出如下所示

    R100    doc/source/user/cellsv2_layout.rst      doc/source/user/cellsv2-layout.rst

  3. cut 命令获取从字段 2 到结尾的内容，给出旧文件名和新文件名

    doc/source/user/cellsv2_layout.rst      doc/source/user/cellsv2-layout.rst

  4. 最后，sed 命令将路径中的 doc/source 部分替换为项目名称和将匹配 URL 系列部分模式。它将 .rst 扩展名转换为 .html，并在行首插入 redirectmatch 指令，得到

    redirectmatch 301 ^/nova/([^/]+)/user/cellsv2_layout.html$        /nova/$1/user/cellsv2-layout.html