如何将主页包含在Sphinx TOC中？ [英] How do I include the homepage in the Sphinx TOC?

问题描述

假设我有一个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

这实际上给了我想要的结果，除了它将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"，因为当您在模板/中的文件中时，这将不起作用。

我是不是漏掉了什么明显的东西？必须有一种方法可以在不中断next链接的情况下将主页放入目录中，并且具有在本地文件系统上工作的动态路径，即使从子文件夹中也是如此。

推荐答案

原来答案就藏在Sphinx的TOC tree page上：

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

将self添加到TOC树可以完美地完成此任务！如果你把它放在一个单独的、隐藏的toctree指令中，它也不会显示在主页的目录上：

.. toctree::
   :hidden:

   self


.. toctree::
   :titlesonly:

   installation
   templating/index

这篇关于如何将主页包含在Sphinx TOC中？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！