如何在Sphinx TOC中加入主页？

Question

假设我有一个Sphinx项目，有以下源文件。

index.rst
installation.rst
templating/
    index.rst
    module.rst
    fieldtype.rst

index.rst (主页)的TOC树如下。

.. toctree::
   :titlesonly:

   installation
   templating/index

我想让我的模板包含一个侧边栏，列出所有3个顶层页面(主页、安装、templatingindex)。

我尝试在主页中添加第二个隐藏的TOC树。

.. toctree::
   :hidden:

   index

.. toctree::
   :titlesonly:

   installation
   templating/index

这实际上给了我想要的结果。除了 它使 next 变量设置为当前页面。所以我模板中的这段代码:

Next up: <a href="{{ next.link }}">{{ next.title }}</a>

...总是从主页输出主页链接。不好。

我一直尝试将实际的主页链接硬编码到模板的侧栏中。

{% set homeClass = 'current' if pagename == 'index' else '' %}
<ul class="{{ homeClass }}">
    <li class="toctree-l1 {{ homeClass }}"><a class="{{ homeClass }} reference internal" href="/index.html">Home</a></li>
</ul>
{{ toctree() }}

这也行得通，只是我不想强迫文档在web服务器的webroot上被访问--我希望它们也能在文件系统中工作。

我不能简单地将URL设置为 "index.html"，因为当你在模板内的文件中时，这样做是行不通的。

我是不是漏掉了什么明显的东西？一定有一种方法可以让主页进入TOC，而又不破坏 next 链接，并且动态路径可以在本地文件系统中工作，甚至可以在子文件夹中工作。

Answer 1

原来答案就藏在Sphinx的显眼处。TOC树页:

特别条目名称： self 代表包含toctree指令的文档。如果你想从toctree中生成一个 "sitemap"，这很有用。

添加 "toctree "指令 self 到TOC树中，完美地解决了这个问题！如果你把它放在单独的、隐藏的toctree指令中，它也不会显示在主页的目录中。如果你把它放在一个单独的、隐藏的toctree指令中，它也不会显示在主页的目录中。

.. toctree::
   :hidden:

   self


.. toctree::
   :titlesonly:

   installation
   templating/index

Answer 2

你是否可以重命名你的Sphinx项目的根toctree页面，或者，templatingindex页面？该 master_doc 变量可以让你为项目中包含根toctree指令的文件命名，而且不一定非要调用 index.rst...在我们的文档项目中，为了解决类似的问题，我们有一个 template/index.html 文件，而我们的根toctree页面实际上叫做 reference.rst.