如何在Sphinx TOC中添加主页？

Question

假设我有一个Sphinx项目,其中包含以下来源:

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

index.rst(主页)有以下TOC树:

.. toctree::
   :titlesonly:

   installation
   templating/index

我希望我的模板包含一个侧栏,列出所有3个顶级页面(主页,安装,模板/索引).

我已经尝试在主页中添加第二个隐藏的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",因为当你在templating /中的文件中时,这将不起作用.

我错过了一些明显的东西吗 必须有一种方法可以将主页放入TOC,而不会破坏next链接和在本地文件系统上工作的动态路径,即使是在子文件夹中也是如此.

Answer 1

事实证明,答案隐藏在Sphinx的TOC树页面上:

特殊条目名称self代表包含toctree指令的文档.如果要从toctree生成"站点地图",这非常有用.

添加self到TOC树就完美了!如果你把它放在一个单独的,隐藏的toctree指令中,它也不会显示在主页的目录上:

.. toctree::
   :hidden:

   self


.. toctree::
   :titlesonly:

   installation
   templating/index