如何在ReadTheDocs导航栏中链接生成的索引页面? [英] How can I link the generated index page in ReadTheDocs navigation bar?

问题描述

我正在使用Sphinx在ReadTheDocs上使用其主题创建文档.构建过程将生成genindex.html文件，该文件可通过以下方式引用:

I'm creating my documentation with Sphinx on ReadTheDocs, using their theme. The build process generates a genindex.html file, which can be referenced with:

Link to the :ref:`genindex` page.

它将创建:

链接到索引页.

我无法将genindex添加到我的toctree中，例如:

I can't add genindex to my toctree, for example like so:

.. toctree:

   foo
   bar
   genindex

因为它是一个自动生成的文件，在渲染时不存在.而且，Sphinx希望genindex是一个名为genindex.rst的lokal文件.

because it's an auto generated file, which does not exist at rendertime. Moreover, Sphinx expects genindex to be a lokal file called genindex.rst.

如何将其添加到我的ToC/导航中?

How can I add it to my ToC / navigation?

推荐答案

就没有人发布更好的解决方案，我将我的解决方法写下来，作为一个可行的解决方案.

Sphinx在构建根目录中将索引创建为denindex.html.不能在toctree指令中引用它，因为该指令引用了ReST文件.那么如何解决呢?

Sphinx creates the index as a denindex.html in the build root directory. It can't be referenced in a toctree directive, because this directive references ReST files. So how to solve it?

因此，让我们创建一个genindex.rst文件，并从toctree指令中引用它.这还将在构建根目录中创建一个genindex.html.所有链接均按预期方式创建. genindex.html文件需要定义一个标题，例如索引"，用作导航栏中的链接标题.

So let's create a genindex.rst file and reference it from a toctree directive. This also creates a genindex.html in the build root directory. All links are created as expected. The genindex.html file needs to define a headline like "Index", which is used as a link title in the navigation bar.

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

After writing all HTML files from ReST files, Sphinx generates its index and overwrites 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
#####

导航栏屏幕截图:

这篇关于如何在ReadTheDocs导航栏中链接生成的索引页面?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！