Sphinx 扩展，将不存在的页面重定向到有效页面。
项目描述
sphinxext-rediraffe
Sphinx 扩展，用于重定向文件
此 Sphinx 扩展将不存在的页面重定向到有效页面。Rediraffe 还可以检查您的 git 仓库中已删除/重命名的文件是否已重定向。
Rediraffe 创建所有指定重定向的图，并通过遍历它将所有内部 URL 指向叶子 URL。这意味着将解决链式重定向。例如，如果配置有 6 个链式重定向，所有 6 个链接都将直接重定向到最后一个链接。最终用户将不会经历超过 1 次重定向。
注意：Rediraffe 支持 html 和 dirhtml 构建器。
安装
python -m pip install sphinxext-rediraffe
使用
在您的 conf.py 中将 sphinxext.rediraffe 添加到扩展列表
extensions = [
"sphinxext.rediraffe",
]
在您的 conf.py 中将 rediraffe_redirects 设置为重定向的字典或文件
差分检查器
差分检查器确保您的 git 仓库中已删除/重命名的文件包含在您的重定向中。
要运行差分检查器，
- 在 conf.py 中设置
rediraffe_branch和rediraffe_redirects。 - 运行
rediraffecheckdiff构建器。
自动重定向构建器
自动重定向构建器可以用来自动将重命名的文件添加到您的重定向文件中。只需运行 rediraffewritediff 构建器。
运行自动重定向器
- 在 conf.py 中设置
rediraffe_branch和rediraffe_redirects。 - 运行
rediraffewritediff构建器。
注意：自动重定向构建器仅与配置文件配合使用。注意：无法自动将已删除的文件添加到您的重定向文件中。
选项
这些值放置在您的 Sphinx 项目的 conf.py 中。
-
rediraffe_branch- 是
rediraffecheckdiff和rediraffewritediff构建器必需的。用于 diff 的分支或提交。
- 是
-
rediraffe_redirects- 必需。包含重定向的文件名或字典
-
rediraffe_template- 可选。用于渲染插入的重定向文件的 Jinja 模板。如未指定，将使用默认模板。此模板仅在 html/htmldir 构建器完成后才能访问；因此，此文件可能是构建过程中生成的。
- rediraffe_template 可用的变量
from_file- 在 rediraffe_redirects 中写入的重定向文件。to_file- from_file 在 rediraffe_redirects 中重定向到的目标文件。from_url- from_url 的 html 文件的路径（由 rediraffe 构建），相对于 outdir。to_url- to_url 的构建 html 文件的路径，相对于 outdir。rel_url- from_url 到 to_url 的相对路径。
-
rediraffe_auto_redirect_perc- 可选。仅由
rediraffewritediff构建器使用。表示在自动重定向之前所需精度的百分比值（整数）。默认为 100。
- 可选。仅由
示例配置
仅重定向（文件）
conf.py
rediraffe_redirects = "redirects.txt"
redirects.txt
# comments start with "#"
"another file.rst" index.rst
another2.rst 'another file.rst'
注意：文件路径可以包含引号（单引号或双引号）。这对于包含空格的文件路径特别有用。
仅重定向（字典）
conf.py
rediraffe_redirects = {
"another.rst": "index.rst",
"another2.rst": "another.rst",
}
重定向 + diff 检查器
conf.py
rediraffe_redirects = "redirects.txt"
rediraffe_branch = "main~1"
带有 Jinja 模板的重定向
conf.py
rediraffe_redirects = "redirects.txt"
rediraffe_template = "template.html"
template.html
<html>
<body>
<p>Your destination is {{to_url}}</p>
</body>
</html>
一个复杂示例可以在 tests/roots/ext/ 中找到。
测试
Rediraffe 使用 pytest 进行测试。要运行测试
- 安装此包
- 安装测试依赖项
python -m pip install -r test-requirements.txt
- 导航到测试目录并运行
python -m pytest --headless
--headless 标志确保在浏览器支持 selenium 测试期间不打开浏览器窗口。
下载文件
下载适用于您平台的文件。如果您不确定选择哪个，请了解有关 安装包 的更多信息。
