如何让 Sphinx 解析 URL 链接，例如/about-manual 到 /about-manual.html答案

【问题标题】：How to make Sphinx resolve URL links from e.g. /about-manual to /about-manual.html如何让 Sphinx 解析 URL 链接，例如/about-manual 到 /about-manual.html
【发布时间】：2020-04-21 08:07:11
【问题描述】：

我正在创建一个 Sphinx 文档，但我很难确定设置结构和链接的“正确”方式。

结构 1#

目前，我的结构如下：

index.rst
   about-manual/index.rst

在我的根index.rst 中，目录树如下：

===========================
Contents
===========================

.. toctree::

   about-manual/index

这会产生以下链接：

https://example.com/docs/             --> Content of index.rst
https://example.com/docs/about-manual --> Content of about-manual/index.rst

这在链接解析方面按预期工作
但是，我不确定这是否是设置 Sphinx 结构的“正确”方式

结构2#

index.rst
about-manual.rst

在我的根index.rst 中，目录树如下：

===========================
Contents
===========================

.. toctree::

   about-manual

这会产生以下链接：

https://example.com/docs/                  --> Content of index.rst
https://example.com/docs/about-manual      --> ERROR
https://example.com/docs/about-manual.html --> Content of about-manual.rst

这会产生更紧凑/简单的 Sphinx 结构
但是，如果用户输入的 URL 末尾没有明确的 .html，则链接会损坏

我是否遗漏了 Sphinx 中的基本配置设置，以使链接解析按照我对“STRUCTURE 2#”的期望工作 - 而不必在末尾添加明确的 .html？

是否可以避免让 Sphinx 文档明确解析为 URL 路径末尾的 index.html？它在根索引上按预期执行此操作，但在“STRUCTURE 1#”中，所有子页面最后都明确显示index.html。

我查看了html_file_suffix 和html_link_suffix，但我也无法使这些工作达到我的目的。

【问题讨论】：

您可以配置您的 Web 服务器以将文件请求（那些缺少尾部斜杠的内容）重定向到 <path>.html 或将 URL 重写为相同的。另一种选择是将每个文件放入根据文件用途命名的自己的目录中，并将其命名为index.rst，这样它的文件名就会解析为index.html，但这有点疯狂。

标签： url-routing python-sphinx

【解决方案1】：

我通过使用 sphinx-build -b dirhtml 而不是 sphinx-build -b html 找到了解决方案（由 sphinx_rtd_theme 团队的 Jesse Tan 提出） - 有关详细信息，请参阅 this link。

它基本上让我可以使用“STRUCTURE 2#”中的方法，但它使用index.html 文件构建输出，该文件以.rst 文件命名的文件夹中结构化。

重要的是，内部链接也更新为不包含index.html 部分。

【讨论】：