如何在 ReadTheDocs 导航栏中链接生成的索引页面？

Question

我正在 ReadTheDocs 上使用 Sphinx 的主题创建我的文档。构建过程会生成一个 genindex.html 文件，可以通过以下方式引用：

Link to the :ref:`genindex` page.

这创造了：

链接到索引页面。

我无法将

genindex

添加到我的目录树中，例如像这样：

.. toctree:

   foo
   bar
   genindex

因为它是自动生成的文件，在渲染时不存在。此外，Sphinx 期望 genindex 是一个名为

genindex.rst

的本地文件。

如何将其添加到我的目录/导航中？

Answer 1

只要没有人发布更好的解决方案，我将写下我的解决方法作为可行的解决方案。

---

Sphinx 在构建根目录中将索引创建为

genindex.html

。不能在

toctree

指令中引用它，因为该指令引用 ReST 文件。那么如何解决呢？

因此，让我们创建一个

genindex.rst

文件并从

toctree

指令引用它。这还会在构建根目录中创建一个

genindex.html

。所有链接均按预期创建。

genindex.html

文件需要定义一个类似“Index”的标题，用作导航栏中的链接标题。

从 ReST 文件写入所有 HTML 文件后，Sphinx 生成其索引并覆盖

genindex.html

。

源文件：

源文件

index.rst

:

.. toctree::
   :caption: Introduction

   chapter1
   chapter2

.. toctree::
   :caption: Main Documentation

   chapter3
   chapter4

.. toctree::
   :caption: Appendix

   genindex

源文件

genindex.rst

:

.. This file is a placeholder and will be replaced

Index
#####

导航栏截图：