python-sphinx - 如何在Sphinx TOC中包含主页？

Question

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

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

index.rst(主页)具有以下目录树:

.. 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”，因为当您使用template /中的文件时，该URL将无法工作。

我是否缺少明显的东西？必须有一种方法可以使主页进入目录，而不会破坏 next链接，并且具有在本地文件系统上工作的动态路径，即使在子文件夹中也是如此。

Answer 1

事实证明，答案隐藏在Sphinx的TOC tree page上:

The special entry name self stands for the document containing the toctree directive. This is useful if you want to generate a “sitemap” from the toctree.

将 self添加到TOC树中可以完美地完成技巧!而且，如果将其放在单独的隐藏toctree指令中，它也不会显示在首页的目录中:

.. toctree::
   :hidden:

   self


.. toctree::
   :titlesonly:

   installation
   templating/index