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上访问文档 - 我希望它们也可以在文件系统中工作。

我不能简单地将网址设置为“index.html”，因为当您在模板中的文件中时，这将不起作用。

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

Answer 1

事实证明，答案隐藏在狮身人面像的TOC tree page：

中

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

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

.. toctree::
   :hidden:

   self


.. toctree::
   :titlesonly:

   installation
   templating/index

Answer 2

您是否可以重命名Sphinx项目的根toctree页面，或者模板/索引页面？ master_doc变量允许您在项目中为包含root toctree指令的文件命名，并且不必在我们的文档项目中调用index.rst ...来解决问题非常类似这个，我们有一个template/index.html文件，我们的root toctree页面实际上被称为reference.rst。

如何在Sphinx TOC中添加主页？

2 个答案: