如何让 Sphinx 解析 URL 来自例如/about-manual 到 /about-manual.html

Question

我正在创建 Sphinx 文档，但我很难确定 "proper" 设置结构和 link 的方法。

结构 1#

目前，我的结构如下所示：

index.rst
   about-manual/index.rst

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

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

.. toctree::

   about-manual/index

结果如下 links:

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

这在 link 分辨率
但是，我不确定这是否是 "proper" 设置我的 Sphinx 结构的方式

结构 2#

index.rst
about-manual.rst

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

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

.. toctree::

   about-manual

结果如下 links:

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

这会导致更多 compact/simple 狮身人面像结构
但是，如果用户输入 URL 而末尾没有显式 .html，则 link 会损坏

我是否缺少 Sphinx 中的基本配置设置，以便使 link 分辨率按照我对 'STRUCTURE 2#' 的预期工作 - 而不必在结束？

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

我查看了 html_file_suffix 和 html_link_suffix，但我也无法将它们用于我的目的。

Answer 1

我找到了一个解决方案，使用 sphinx-build -b dirhtml 而不是 sphinx-build -b html（由 sphinx_rtd_theme 团队的 Jesse Tan 提出）——详情请参阅 this link。

它基本上让我使用 'STRUCTURE 2#' 中的方法，但它使用 index.html 文件构建输出，这些文件在根据 .rst 文件命名的文件夹中构建。

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

如何让 Sphinx 解析 URL 来自例如/about-manual 到 /about-manual.html

How to make Sphinx resolve URL links from e.g. /about-manual to /about-manual.html

url-routing

python-sphinx