如何将主页包含在 Sphinx 目录中？

假设我有一个 Sphinx 项目，其来源如下：

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

index.rst（主页）具有以下目录树：

.. toctree::
   :titlesonly:

   installation
   templating/index

我希望我的模板包含一个侧边栏，列出所有 3 个顶级页面（主页、安装、模板/索引）。

我尝试在主页中添加第二个隐藏的目录树：

.. toctree::
   :hidden:

   index

.. toctree::
   :titlesonly:

   installation
   templating/index

这实际上给了我想要的结果，except它使得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() }}

这也有效，只是我不想强制在网络服务器的网络根目录上访问文档 – 我希望它们也可以从文件系统工作。

我不能简单地将 URL 设置为“index.html”，因为当您位于 template/ 中的文件中时，这将不起作用。

我错过了一些明显的事情吗？必须有一种方法可以让主页进入目录，而不破坏next链接并具有可在本地文件系统上运行的动态路径，甚至可以在子文件夹内运行。

事实证明，答案就隐藏在狮身人面像的显而易见的地方目录树页面 http://sphinx-doc.org/markup/toctree.html:

特殊条目名称self代表包含 toctree 指令的文档。如果您想从目录树生成“站点地图”，这非常有用。

Adding selfTOC 树完美地达到了目的！如果您将其放置在单独的隐藏 toctree 指令中，它也不会显示在主页目录中：

.. toctree::
   :hidden:

   self


.. toctree::
   :titlesonly:

   installation
   templating/index