31

假设我有一个 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”,因为当您在模板/中的文件中时,这将不起作用。

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

4

2 回答 2

45

原来答案隐藏在 Sphinx 的目录树页面上

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

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

.. toctree::
   :hidden:

   self


.. toctree::
   :titlesonly:

   installation
   templating/index
于 2013-04-30T14:50:49.853 回答
2

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

于 2013-04-25T15:55:29.873 回答